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

package/dist/index.mjs

@@ -0,0 +1,1237 @@
+import * as R from "ramda";
+import * as fastq from "fastq";
+import { Exception, createProxyResponse } from "keq";
+import dayjs from "dayjs";
+import { openDB } from "idb";
+//#region src/exceptions/cache-exception.ts
+var CacheException = class extends Exception {
+	constructor(message) {
+		super(`[@keq-request/cache] ${message}`);
+	}
+};
+//#endregion
+//#region src/utils/get-response-bytes.ts
+async function getResponseBytes(response) {
+	const contentLength = response.headers.get("content-length");
+	if (contentLength) return parseInt(contentLength);
+	return (await response.clone().arrayBuffer()).byteLength;
+}
+//#endregion
+//#region src/constants/max-expired-at.ts
+const MAX_EXPIRED_AT = /* @__PURE__ */ new Date(864e13);
+//#endregion
+//#region src/constants/eviction.enum.ts
+let Eviction = /* @__PURE__ */ function(Eviction) {
+	Eviction["LRU"] = "lru";
+	Eviction["LFU"] = "lfu";
+	Eviction["RANDOM"] = "random";
+	Eviction["TTL"] = "ttl";
+	return Eviction;
+}({});
+//#endregion
+//#region src/constants/size.enum.ts
+let Size = /* @__PURE__ */ function(Size) {
+	Size[Size["B"] = 1] = "B";
+	Size[Size["KB"] = 1024] = "KB";
+	Size[Size["MB"] = 1048576] = "MB";
+	Size[Size["GB"] = 1073741824] = "GB";
+	return Size;
+}({});
+//#endregion
+//#region src/utils/logger.ts
+var Logger = class {
+	static debug(...args) {
+		console.debug("[@keq-request/cache] [DEBUG] ", ...args);
+	}
+	static error(...args) {
+		console.error("[@keq-request/cache] [ERROR] ", ...args);
+	}
+};
+//#endregion
+//#region src/utils/random.ts
+function random(min, max) {
+	return Math.floor(Math.random() * (max - min)) + min;
+}
+//#endregion
+//#region src/strategies/cache-first.ts
+const cacheFirst = async function cacheFirst(handler, context, next) {
+	const [cacheKey, cacheValue] = await handler.getCache();
+	if (handler.options.debug) Logger.debug([
+		"",
+		`Request: ${context.request.method.toUpperCase()} ${context.request.__url__.href}`,
+		"Strategy: Cache First",
+		`Cache Key: ${cacheKey}`,
+		`Cache Status: ${cacheValue ? "HIT" : "MISS"}`
+	].join("\n"));
+	if (cacheValue) {
+		context.emitter.emit("cache:hit", {
+			key: cacheKey,
+			response: cacheValue.response,
+			context
+		});
+		context.res = cacheValue.response;
+		return;
+	}
+	context.emitter.emit("cache:miss", {
+		key: cacheKey,
+		context
+	});
+	await next();
+	const [, entry] = await handler.setCache(context);
+	if (handler.options.debug) Logger.debug([
+		"",
+		`Request: ${context.request.method.toUpperCase()} ${context.request.__url__.href}`,
+		"Strategy: Cache First",
+		`Cache Key: ${cacheKey}`,
+		`ACTIONS: ${entry ? "UPDATED" : "EXCLUDED"}`
+	].join("\n"));
+	if (entry) context.emitter.emit("cache:update", {
+		key: entry.key,
+		oldResponse: void 0,
+		newResponse: entry.response,
+		context
+	});
+};
+//#endregion
+//#region src/strategies/network-first.ts
+const networkFirst = async function networkFirst(handler, context, next) {
+	try {
+		await next();
+		const [cacheKey, cache] = await handler.getCache();
+		const [, entry] = await handler.setCache(context);
+		if (handler.options.debug) Logger.debug([
+			"",
+			`Request: ${context.request.method.toUpperCase()} ${context.request.__url__.href}`,
+			"Strategy: Network First",
+			`Cache Key: ${cacheKey}`,
+			`ACTIONS: ${entry ? "UPDATED" : "EXCLUDED"}`
+		].join("\n"));
+		if (entry) context.emitter.emit("cache:update", {
+			key: entry.key,
+			oldResponse: cache?.response,
+			newResponse: entry.response,
+			context
+		});
+	} catch (err) {
+		const [cacheKey, cache] = await handler.getCache();
+		if (handler.options.debug) Logger.debug([
+			"",
+			`Request: ${context.request.method.toUpperCase()} ${context.request.__url__.href}`,
+			"Strategy: Network First",
+			`Cache Key: ${cacheKey}`,
+			`Cache Status: ${cache ? "HIT" : "MISS"}`
+		].join("\n"));
+		if (!cache) {
+			context.emitter.emit("cache:miss", {
+				key: cacheKey,
+				context
+			});
+			throw err;
+		}
+		context.emitter.emit("cache:hit", {
+			key: cacheKey,
+			response: cache.response,
+			context
+		});
+		context.res = cache.response;
+	}
+};
+//#endregion
+//#region src/strategies/network-only.ts
+const networkOnly = async function(handler, context, next) {
+	await next();
+};
+//#endregion
+//#region src/strategies/stale-while-revalidate.ts
+const staleWhileRevalidate = async function(handler, context, next) {
+	const [cacheKey, cache] = await handler.getCache();
+	if (handler.options.debug) Logger.debug([
+		"",
+		`Request: ${context.request.method.toUpperCase()} ${context.request.__url__.href}`,
+		"Strategy: Stale While Revalidate",
+		`Cache Key: ${cacheKey}`,
+		`Cache Status: ${cache ? "HIT" : "MISS"}`
+	].join("\n"));
+	if (cache) context.emitter.emit("cache:hit", {
+		key: cacheKey,
+		response: cache.response,
+		context
+	});
+	else context.emitter.emit("cache:miss", {
+		key: cacheKey,
+		context
+	});
+	if (cache) {
+		const orchestrator = context.orchestration.fork();
+		context.res = cache.response;
+		setTimeout(async () => {
+			try {
+				await orchestrator.execute();
+				const context = orchestrator.context;
+				const [cacheKey, entry] = await handler.setCache(context);
+				if (handler.options.debug) Logger.debug([
+					"",
+					`Request: ${context.request.method.toUpperCase()} ${context.request.__url__.href}`,
+					"Strategy: Stale While Revalidate",
+					`Cache Key: ${cacheKey}`,
+					`ACTIONS: ${entry ? "UPDATED" : "EXCLUDED"}`
+				].join("\n"));
+				if (entry) context.emitter.emit("cache:update", {
+					key: cacheKey,
+					oldResponse: cache.response,
+					newResponse: entry.response,
+					context
+				});
+			} catch (err) {}
+		}, 1);
+	} else {
+		await next();
+		const [cacheKey, entry] = await handler.setCache(context);
+		if (handler.options.debug) Logger.debug([
+			"",
+			`Request: ${context.request.method.toUpperCase()} ${context.request.__url__.href}`,
+			"Strategy: Stale While Revalidate",
+			`Cache Key: ${cacheKey}`,
+			`ACTIONS: ${entry ? "UPDATED" : "EXCLUDED"}`
+		].join("\n"));
+		if (entry) context.emitter.emit("cache:update", {
+			key: cacheKey,
+			oldResponse: void 0,
+			newResponse: entry.response,
+			context
+		});
+	}
+};
+//#endregion
+//#region src/constants/strategy.enum.ts
+const Strategy = {
+	STALE_WHILE_REVALIDATE: staleWhileRevalidate,
+	NETWORK_FIRST: networkFirst,
+	NETWORK_ONLY: networkOnly,
+	CACHE_FIRST: cacheFirst
+};
+//#endregion
+//#region \0@oxc-project+runtime@0.127.0/helpers/typeof.js
+function _typeof(o) {
+	"@babel/helpers - typeof";
+	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
+		return typeof o;
+	} : function(o) {
+		return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o;
+	}, _typeof(o);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.127.0/helpers/toPrimitive.js
+function toPrimitive(t, r) {
+	if ("object" != _typeof(t) || !t) return t;
+	var e = t[Symbol.toPrimitive];
+	if (void 0 !== e) {
+		var i = e.call(t, r || "default");
+		if ("object" != _typeof(i)) return i;
+		throw new TypeError("@@toPrimitive must return a primitive value.");
+	}
+	return ("string" === r ? String : Number)(t);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.127.0/helpers/toPropertyKey.js
+function toPropertyKey(t) {
+	var i = toPrimitive(t, "string");
+	return "symbol" == _typeof(i) ? i : i + "";
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.127.0/helpers/defineProperty.js
+function _defineProperty(e, r, t) {
+	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
+		value: t,
+		enumerable: !0,
+		configurable: !0,
+		writable: !0
+	}) : e[r] = t, e;
+}
+//#endregion
+//#region src/cache-entry/cache-entry.ts
+var CacheEntry = class CacheEntry {
+	constructor(options) {
+		_defineProperty(this, "key", void 0);
+		_defineProperty(this, "response", void 0);
+		_defineProperty(
+			this,
+			/**
+			* @en bytes
+			* @zh 字节数
+			*/
+			"size",
+			void 0
+		);
+		_defineProperty(this, "expiredAt", void 0);
+		this.key = options.key;
+		this.response = createProxyResponse(options.response);
+		this.size = options.size;
+		this.expiredAt = options.expiredAt ?? MAX_EXPIRED_AT;
+	}
+	static async build(options) {
+		const expiredAt = "expiredAt" in options ? options.expiredAt : "ttl" in options && typeof options.ttl === "number" && options.ttl > 0 ? new Date(Date.now() + options.ttl * 1e3) : MAX_EXPIRED_AT;
+		const response = options.response.clone();
+		return new CacheEntry({
+			key: options.key,
+			response,
+			size: options.size ?? await getResponseBytes(response),
+			expiredAt
+		});
+	}
+	clone() {
+		return new CacheEntry({
+			key: this.key,
+			response: this.response.clone(),
+			size: this.size,
+			expiredAt: this.expiredAt
+		});
+	}
+	assignResponseHeaders(headers) {
+		this.response = new Response(this.response.body, {
+			status: this.response.status,
+			statusText: this.response.statusText,
+			headers
+		});
+	}
+};
+//#endregion
+//#region src/request-cache-handler/request-cache-handler.ts
+var RequestCacheHandler = class {
+	constructor(cacheKey, storage, options) {
+		this.cacheKey = cacheKey;
+		this.storage = storage;
+		this.options = options;
+	}
+	/**
+	* Resolve cache key for request context
+	*/
+	static resolveRequestCacheKey(context, options) {
+		if (typeof options.key === "string") return options.key;
+		else if (typeof options.key === "function") return options.key(context);
+		else if (R.isNil(options.key) && context.locationId) return context.locationId;
+		else throw new CacheException("Cannot resolve cache key");
+	}
+	/**
+	* Get cache from storage
+	*/
+	async getCache() {
+		const key = this.cacheKey;
+		if (this.options.serverTiming) {
+			const startAt = /* @__PURE__ */ new Date();
+			const entry = await this.storage.get(key);
+			if (entry) {
+				const dur = (/* @__PURE__ */ new Date()).getTime() - startAt.getTime();
+				const HeadersWithServerTiming = new Headers(entry.response.headers);
+				HeadersWithServerTiming.set("Server-Timing", `keq-cache; dur=${dur}; desc="HIT"`);
+				entry.assignResponseHeaders(HeadersWithServerTiming);
+			}
+			return [key, entry];
+		}
+		return [key, await this.storage.get(key)];
+	}
+	/**
+	* Store response that in context to storage
+	*/
+	async setCache(context) {
+		const options = this.options;
+		const key = this.cacheKey;
+		if (!context.response) return [key, void 0];
+		if (options.exclude && await options.exclude(context.response)) return [key, void 0];
+		const entry = await CacheEntry.build({
+			key,
+			response: context.response,
+			ttl: options.ttl
+		});
+		this.storage.set(entry);
+		return [key, entry];
+	}
+};
+//#endregion
+//#region src/cache.ts
+function cache(options) {
+	const storage = options.storage;
+	const rules = options?.rules || [];
+	return async function cache(ctx, next) {
+		if (ctx.options.cache === false) {
+			await next();
+			return;
+		}
+		let requestCacheOptions = ctx.options.cache;
+		const rule = rules.find((rule) => {
+			if (rule.pattern === void 0 || rule.pattern === true) return true;
+			if (typeof rule.pattern === "function") return rule.pattern(ctx);
+			return rule.pattern.test(ctx.request.__url__.href);
+		});
+		if (rule) requestCacheOptions = R.mergeRight(rule, requestCacheOptions || {});
+		if (!requestCacheOptions || R.isEmpty(requestCacheOptions)) {
+			await next();
+			return;
+		}
+		if (!requestCacheOptions.key) requestCacheOptions.key = options.keyFactory;
+		if (!ctx.locationId && !requestCacheOptions.key) {
+			console.warn("[@keq/cache] Warning: Cannot resolve Cache Key. Cache is skipped.");
+			await next();
+			return;
+		}
+		if (requestCacheOptions.serverTiming === void 0 && options.serverTiming !== void 0) requestCacheOptions.serverTiming = options.serverTiming;
+		const cacheKey = RequestCacheHandler.resolveRequestCacheKey(ctx, requestCacheOptions);
+		const handler = new RequestCacheHandler(cacheKey, storage, requestCacheOptions);
+		const strategy = requestCacheOptions.strategy;
+		if (requestCacheOptions.concurrent) await strategy(handler, ctx, next);
+		else {
+			if (!ctx.global.core) ctx.global.core = {};
+			if (!ctx.global.core.cache) ctx.global.core.cache = {};
+			if (!ctx.global.core.cache[cacheKey]) ctx.global.core.cache[cacheKey] = fastq.promise(async ({ next }) => {
+				await next();
+			}, 1);
+			await ctx.global.core.cache[cacheKey].push({ next: async () => {
+				await strategy(handler, ctx, next);
+			} });
+		}
+	};
+}
+//#endregion
+//#region src/storage/keq-cache-storage.ts
+var KeqCacheStorage = class {};
+//#endregion
+//#region src/storage/internal-storage/internal-storage.ts
+var InternalStorage = class extends KeqCacheStorage {
+	constructor(options) {
+		super();
+		_defineProperty(this, "__id__", Math.random().toString(36).slice(2));
+		_defineProperty(this, "__size__", void 0);
+		_defineProperty(this, "__debug__", void 0);
+		_defineProperty(this, "__onCacheGet__", void 0);
+		_defineProperty(this, "__onCacheSet__", void 0);
+		_defineProperty(this, "__onCacheRemove__", void 0);
+		_defineProperty(this, "__onCacheEvict__", void 0);
+		_defineProperty(this, "__onCacheExpired__", void 0);
+		if (options?.size && (typeof options?.size !== "number" || options.size <= 0)) throw new CacheException(`Invalid size: ${String(options?.size)}`);
+		this.__size__ = options?.size ?? Infinity;
+		this.__debug__ = !!options?.debug;
+		this.__onCacheGet__ = options?.onCacheGet;
+		this.__onCacheSet__ = options?.onCacheSet;
+		this.__onCacheRemove__ = options?.onCacheRemove;
+		this.__onCacheEvict__ = options?.onCacheEvict;
+		this.debug((log) => log("Storage Created: ", this));
+	}
+	debug(fn) {
+		if (this.__debug__) fn((...args) => {
+			Logger.debug(`[Storage(${this.__id__})]`, ...args);
+		});
+	}
+};
+//#endregion
+//#region src/storage/memory-storage/utils/humanize-size.ts
+/**
+* @en Humanize size in bytes to KB, MB, GB
+* @zh 将字节数转换为 KB、MB、GB 等易读格式
+*/
+function humanizeSize(size) {
+	if (size < 1024) return `${size} B`;
+	if (size < 1024 * 1024) return `${(size / 1024).toFixed(2)} KB`;
+	if (size < 1024 * 1024 * 1024) return `${(size / (1024 * 1024)).toFixed(2)} MB`;
+	return `${(size / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+//#endregion
+//#region src/storage/memory-storage/utils/serialize-response-body.ts
+/**
+* @en Serialize the response body based on content-type
+* @zh 根据 content-type 序列化响应体
+*/
+async function serializeResponseBody(response) {
+	const contentType = response.headers.get("content-type") ?? "";
+	try {
+		if (contentType.includes("application/json")) {
+			const json = await response.json();
+			return JSON.stringify(json);
+		}
+		if (contentType.includes("text/") || contentType.includes("application/xml") || contentType.includes("application/javascript")) return await response.text();
+		return "[Binary or unsupported content]";
+	} catch {
+		return "[Unable to serialize]";
+	}
+}
+//#endregion
+//#region src/storage/memory-storage/base-memory-storage.ts
+var BaseMemoryStorage = class extends InternalStorage {
+	constructor(..._args) {
+		super(..._args);
+		_defineProperty(this, "storage", /* @__PURE__ */ new Map());
+		_defineProperty(this, "visitTimeRecords", /* @__PURE__ */ new Map());
+		_defineProperty(this, "visitCountRecords", /* @__PURE__ */ new Map());
+		_defineProperty(this, "lastEvictExpiredTime", dayjs());
+	}
+	get size() {
+		const used = R.sum(R.pluck("size", [...this.storage.values()]));
+		return {
+			used,
+			free: this.__size__ > used ? this.__size__ - used : 0
+		};
+	}
+	get(key) {
+		this.evictExpired();
+		const entry = this.storage.get(key);
+		this.visitCountRecords.set(key, (this.visitCountRecords.get(key) ?? 0) + 1);
+		this.visitTimeRecords.set(key, /* @__PURE__ */ new Date());
+		if (!entry) this.debug((log) => log(`Entry(${key}) Not Found`));
+		else this.debug((log) => log(`Entry(${key}) Found: `, entry));
+		return entry?.clone();
+	}
+	set(value) {
+		if (!this.evict(value.size)) {
+			this.debug((log) => log("Storage Size Not Enough: ", this.size.free, " < ", value.size));
+			return;
+		}
+		this.storage.set(value.key, value);
+		this.visitTimeRecords.set(value.key, /* @__PURE__ */ new Date());
+		this.visitCountRecords.set(value.key, this.visitCountRecords.get(value.key) ?? 0);
+		this.debug((log) => log("Entry Added: ", value));
+		this.debug((log) => log("Storage Size: ", this.size));
+	}
+	__remove__(keys) {
+		for (const key of keys) {
+			const entry = this.storage.get(key);
+			if (!entry) return;
+			this.storage.delete(key);
+			this.visitCountRecords.delete(key);
+			this.visitTimeRecords.delete(key);
+			this.debug((log) => log("Entry Removed: ", entry));
+			this.debug((log) => log("Storage Size: ", this.size));
+		}
+	}
+	remove(key) {
+		this.__remove__([key]);
+	}
+	/**
+	* @zh 清除过期的缓存
+	*/
+	evictExpired() {
+		const now = dayjs();
+		if (now.diff(this.lastEvictExpiredTime, "second") < 1) return;
+		const keys = [];
+		for (const [key, entry] of this.storage.entries()) if (entry.expiredAt && now.isAfter(entry.expiredAt)) keys.push(key);
+		this.__remove__(keys);
+		this.__onCacheExpired__?.({ keys });
+	}
+	/**
+	* @en Evict the storage to make sure the size is enough
+	* @zh 清除缓存以确保有足够的空间
+	*
+	* @return {boolean} - is evicted successfully
+	*/
+	evict(expectSize) {
+		this.evictExpired();
+		return this.size.free >= expectSize;
+	}
+	/**
+	* @en Print all cached data using console.table for debugging
+	* @zh 使用 console.table 打印所有缓存数据，用于调试
+	*/
+	async print() {
+		if (this.storage.size === 0) {
+			console.log("MemoryStorage is empty");
+			return;
+		}
+		const entries = await Promise.all([...this.storage.entries()].map(async ([key, entry]) => {
+			const body = await serializeResponseBody(entry.response.clone());
+			return {
+				key,
+				size: humanizeSize(entry.size),
+				"Expired Time": entry.expiredAt.getTime() >= MAX_EXPIRED_AT.getTime() ? "-" : entry.expiredAt.toISOString(),
+				"Visit Count": this.visitCountRecords.get(key) ?? 0,
+				"Last Visit Time": this.visitTimeRecords.get(key)?.toISOString() ?? "-",
+				"Response Status": entry.response.status,
+				"Response URL": entry.response.url,
+				"Response Body": body
+			};
+		}));
+		console.table(entries);
+	}
+};
+//#endregion
+//#region src/storage/memory-storage/ttl-memory-storage.ts
+var TTLMemoryStorage = class extends BaseMemoryStorage {
+	constructor(options) {
+		super(options);
+	}
+	get(key) {
+		const entry = super.get(key);
+		this.__onCacheGet__?.({ key });
+		return entry;
+	}
+	set(value) {
+		super.set(value);
+		this.__onCacheSet__?.({ key: value.key });
+	}
+	remove(key) {
+		super.remove(key);
+		this.__onCacheRemove__?.({ key });
+	}
+	evict(expectSize) {
+		if (expectSize > this.__size__) {
+			this.debug((log) => log("Storage Size Not Enough: ", this.__size__, " < ", expectSize));
+			return false;
+		}
+		this.evictExpired();
+		let deficitSize = expectSize - this.size.free;
+		if (deficitSize <= 0) return true;
+		const entries = [...this.storage.values()].sort((a, b) => {
+			const aExpiredAt = dayjs(a.expiredAt);
+			const bExpiredAt = dayjs(b.expiredAt);
+			return aExpiredAt.isBefore(bExpiredAt) ? 1 : -1;
+		});
+		if (R.sum(R.pluck("size", entries)) < deficitSize) {
+			this.debug((log) => log("Storage Size Not Enough: ", this.size.free, " < ", deficitSize));
+			return false;
+		}
+		const keys = [];
+		while (deficitSize > 0 && entries.length) {
+			const entry = entries.pop();
+			deficitSize -= entry.size;
+			keys.push(entry.key);
+		}
+		this.__remove__(keys);
+		this.__onCacheEvict__?.({ keys });
+		return true;
+	}
+};
+//#endregion
+//#region src/storage/memory-storage/random-memory-storage.ts
+var RandomMemoryStorage = class extends BaseMemoryStorage {
+	constructor(options) {
+		super(options);
+	}
+	get(key) {
+		const entry = super.get(key);
+		this.__onCacheGet__?.({ key });
+		return entry;
+	}
+	set(value) {
+		super.set(value);
+		this.__onCacheSet__?.({ key: value.key });
+	}
+	remove(key) {
+		super.remove(key);
+		this.__onCacheRemove__?.({ key });
+	}
+	evict(expectSize) {
+		if (expectSize > this.__size__) {
+			this.debug((log) => log("Storage Size Not Enough: ", this.__size__, " < ", expectSize));
+			return false;
+		}
+		this.evictExpired();
+		let deficitSize = expectSize - this.size.free;
+		if (deficitSize <= 0) return true;
+		const entries = [...this.storage.values()];
+		const keys = [];
+		while (deficitSize > 0 && entries.length) {
+			const index = random(0, entries.length - 1);
+			const entry = entries[index];
+			deficitSize -= entry.size;
+			entries.splice(index, 1);
+			keys.push(entry.key);
+		}
+		this.__remove__(keys);
+		this.__onCacheEvict__?.({ keys });
+		return true;
+	}
+};
+//#endregion
+//#region src/storage/memory-storage/lru-memory-storage.ts
+var LRUMemoryStorage = class extends BaseMemoryStorage {
+	constructor(options) {
+		super(options);
+	}
+	get(key) {
+		const entry = super.get(key);
+		this.__onCacheGet__?.({ key });
+		return entry;
+	}
+	set(value) {
+		super.set(value);
+		this.__onCacheSet__?.({ key: value.key });
+	}
+	remove(key) {
+		super.remove(key);
+		this.__onCacheRemove__?.({ key });
+	}
+	evict(expectSize) {
+		if (expectSize > this.__size__) {
+			this.debug((log) => log("Storage Size Not Enough: ", this.__size__, " < ", expectSize));
+			return false;
+		}
+		this.evictExpired();
+		let deficitSize = expectSize - this.size.free;
+		if (deficitSize <= 0) return true;
+		const entries = [...this.storage.values()].sort((a, b) => {
+			const aVisitAt = this.visitTimeRecords.get(a.key);
+			const bVisitAt = this.visitTimeRecords.get(b.key);
+			if (aVisitAt === bVisitAt) return 0;
+			if (!aVisitAt) return 1;
+			if (!bVisitAt) return -1;
+			return dayjs(aVisitAt).isBefore(dayjs(bVisitAt)) ? 1 : -1;
+		});
+		const keys = [];
+		while (deficitSize > 0 && entries.length) {
+			const entry = entries.pop();
+			deficitSize -= entry.size;
+			keys.push(entry.key);
+		}
+		this.__remove__(keys);
+		this.__onCacheEvict__?.({ keys });
+		return true;
+	}
+};
+//#endregion
+//#region src/storage/memory-storage/lfu-memory-storage.ts
+var LFUMemoryStorage = class extends BaseMemoryStorage {
+	constructor(options) {
+		super(options);
+	}
+	get(key) {
+		const entry = super.get(key);
+		this.__onCacheGet__?.({ key });
+		return entry;
+	}
+	set(value) {
+		super.set(value);
+		this.__onCacheSet__?.({ key: value.key });
+	}
+	remove(key) {
+		super.remove(key);
+		this.__onCacheRemove__?.({ key });
+	}
+	evict(expectSize) {
+		if (expectSize > this.__size__) {
+			this.debug((log) => log("Storage Size Not Enough: ", this.__size__, " < ", expectSize));
+			return false;
+		}
+		this.evictExpired();
+		let deficitSize = expectSize - this.size.free;
+		if (deficitSize <= 0) return true;
+		const entries = [...this.storage.values()].sort((a, b) => {
+			const aVisitCount = this.visitCountRecords.get(a.key) || 0;
+			return (this.visitCountRecords.get(b.key) || 0) - aVisitCount;
+		});
+		const keys = [];
+		while (deficitSize > 0 && entries.length) {
+			const entry = entries.pop();
+			deficitSize -= entry.size;
+			keys.push(entry.key);
+		}
+		this.__remove__(keys);
+		this.__onCacheEvict__?.({ keys });
+		return true;
+	}
+};
+//#endregion
+//#region src/storage/memory-storage/memory-storage.ts
+var MemoryStorage = class extends KeqCacheStorage {
+	constructor(options) {
+		super();
+		_defineProperty(this, "storage", void 0);
+		const eviction = options?.eviction || "lru";
+		if (eviction === "ttl") this.storage = new TTLMemoryStorage(options);
+		else if (eviction === "random") this.storage = new RandomMemoryStorage(options);
+		else if (eviction === "lru") this.storage = new LRUMemoryStorage(options);
+		else if (eviction === "lfu") this.storage = new LFUMemoryStorage(options);
+		else throw new TypeError(`Invalid eviction: ${String(eviction)}`);
+	}
+	set(entry) {
+		return this.storage.set(entry);
+	}
+	get(key) {
+		return this.storage.get(key);
+	}
+	remove(key) {
+		return this.storage.remove(key);
+	}
+	async print() {
+		return this.storage.print();
+	}
+};
+//#endregion
+//#region src/storage/indexed-db-storage/constants/default-table-name.ts
+const DEFAULT_TABLE_NAME = "keq_cache_indexed_db_storage";
+//#endregion
+//#region src/storage/indexed-db-storage/base-indexed-db-storage.ts
+var BaseIndexedDBStorage = class extends InternalStorage {
+	constructor(options) {
+		super(options);
+		_defineProperty(this, "tableName", DEFAULT_TABLE_NAME);
+		_defineProperty(this, "db", void 0);
+		_defineProperty(this, "lastEvictExpiredTime", dayjs(0));
+		if (options?.tableName === "keq_cache_indexed_db_storage") throw new CacheException(`IndexedDBStorage name cannot be "${DEFAULT_TABLE_NAME}"`);
+		this.tableName = options?.tableName || "keq_cache_indexed_db_storage";
+	}
+	async openDB() {
+		if (this.db) return this.db;
+		const tableName = this.tableName;
+		const db = await openDB(tableName, 2, {
+			upgrade(db) {
+				if (!db.objectStoreNames.contains("metadata")) db.createObjectStore("metadata", { keyPath: "key" }).createIndex("expiredAt", "expiredAt");
+				if (!db.objectStoreNames.contains("response")) db.createObjectStore("response", { keyPath: "key" }).createIndex("responseStatus", "responseStatus");
+				if (!db.objectStoreNames.contains("visits")) {
+					const visitsStore = db.createObjectStore("visits", { keyPath: "key" });
+					visitsStore.createIndex("visitCount", "visitCount");
+					visitsStore.createIndex("lastVisitedAt", "lastVisitedAt");
+				}
+			},
+			blocked() {
+				Logger.error(`[@keq-request/cache] IndexedDB Table ${tableName} is blocked`);
+			},
+			blocking() {
+				Logger.error(`[@keq-request/cache] IndexedDB Table ${tableName} is blocking`);
+			},
+			terminated() {
+				Logger.error(`[@keq-request/cache] IndexedDB Table ${tableName} is terminated`);
+			}
+		});
+		this.db = db;
+		return db;
+	}
+	async getSize() {
+		const items = await (await this.openDB()).getAll("metadata");
+		const used = R.sum(items.map((entry) => entry.size));
+		return {
+			used,
+			free: this.__size__ - used
+		};
+	}
+	async get(key) {
+		await this.evictExpired();
+		try {
+			const db = await this.openDB();
+			const dbMetadata = await db.get("metadata", key);
+			const dbResponse = await db.get("response", key);
+			const dbVisits = await db.get("visits", key);
+			if (!dbMetadata || !dbResponse) return;
+			await db.put("visits", {
+				key: dbMetadata.key,
+				visitCount: dbVisits ? dbVisits.visitCount + 1 : 1,
+				lastVisitedAt: /* @__PURE__ */ new Date()
+			});
+			const response = new Response(dbResponse.responseBody, {
+				status: dbResponse.responseStatus,
+				headers: new Headers(dbResponse.responseHeaders),
+				statusText: dbResponse.responseStatusText
+			});
+			return await CacheEntry.build({
+				key: dbMetadata.key,
+				expiredAt: dbMetadata.expiredAt,
+				response,
+				size: dbMetadata.size
+			});
+		} catch (error) {
+			return;
+		}
+	}
+	async set(entry) {
+		try {
+			if (!await this.evict(entry.size)) {
+				const size = await this.getSize();
+				this.debug((log) => log(`Storage Size Not Enough: ${size.free} < ${entry.size}`));
+				return;
+			}
+			const dbMetadata = {
+				key: entry.key,
+				size: entry.size,
+				expiredAt: entry.expiredAt,
+				visitedAt: /* @__PURE__ */ new Date(),
+				visitCount: 0
+			};
+			const response = entry.response.clone();
+			const dbResponse = {
+				key: entry.key,
+				responseBody: await response.arrayBuffer(),
+				responseHeaders: [...response.headers.entries()],
+				responseStatus: response.status,
+				responseStatusText: response.statusText
+			};
+			const tx = (await this.openDB()).transaction([
+				"metadata",
+				"response",
+				"visits"
+			], "readwrite");
+			const metadataStore = tx.objectStore("metadata");
+			const responseStore = tx.objectStore("response");
+			const visitsStore = tx.objectStore("visits");
+			const dbVisits = await visitsStore.get(entry.key) || {
+				key: entry.key,
+				visitCount: 0,
+				lastVisitedAt: /* @__PURE__ */ new Date()
+			};
+			await Promise.all([
+				metadataStore.put(dbMetadata),
+				responseStore.put(dbResponse),
+				visitsStore.put(dbVisits)
+			]);
+			await tx.done;
+		} catch (error) {
+			return;
+		}
+	}
+	async __remove__(tx, keys) {
+		await Promise.all(R.unnest(keys.map((key) => [
+			tx.objectStore("metadata").delete(key),
+			tx.objectStore("response").delete(key),
+			tx.objectStore("visits").delete(key)
+		])));
+	}
+	async remove(key) {
+		try {
+			const tx = (await this.openDB()).transaction([
+				"metadata",
+				"response",
+				"visits"
+			], "readwrite");
+			await this.__remove__(tx, [key]);
+			await tx.done;
+		} catch (error) {
+			return;
+		}
+	}
+	/**
+	* @zh 清除过期的缓存
+	*/
+	async evictExpired() {
+		const now = dayjs();
+		if (now.diff(this.lastEvictExpiredTime, "second") < 1) return;
+		this.lastEvictExpiredTime = now;
+		try {
+			const tx = (await this.openDB()).transaction([
+				"metadata",
+				"response",
+				"visits"
+			], "readwrite");
+			let cursor = await tx.objectStore("metadata").index("expiredAt").openCursor(IDBKeyRange.upperBound(now.toDate()));
+			const expiredKeys = [];
+			while (cursor) if (dayjs(cursor.value.expiredAt).isBefore(now)) {
+				expiredKeys.push(cursor.value.key);
+				cursor = await cursor.continue();
+			} else break;
+			await this.__remove__(tx, expiredKeys);
+			await tx.done;
+			this.__onCacheExpired__?.({ keys: expiredKeys });
+		} catch (error) {
+			return;
+		}
+	}
+};
+//#endregion
+//#region src/storage/indexed-db-storage/random-indexed-db-storage.ts
+var RandomIndexedDBStorage = class extends BaseIndexedDBStorage {
+	constructor(options) {
+		super(options);
+	}
+	async get(key) {
+		const entry = await super.get(key);
+		this.__onCacheGet__?.({ key });
+		return entry;
+	}
+	async set(value) {
+		await super.set(value);
+		this.__onCacheSet__?.({ key: value.key });
+	}
+	async remove(key) {
+		await super.remove(key);
+		this.__onCacheRemove__?.({ key });
+	}
+	async evict(expectSize) {
+		await this.evictExpired();
+		let deficitSize = expectSize - (await this.getSize()).free;
+		if (deficitSize <= 0) return true;
+		const tx = (await this.openDB()).transaction([
+			"metadata",
+			"response",
+			"visits"
+		], "readwrite");
+		const metadatas = await tx.objectStore("metadata").getAll();
+		const totalSize = R.sum(metadatas.map((m) => m.size));
+		if (totalSize < deficitSize) {
+			this.debug((log) => log(`Storage Size Not Enough, deficit size: ${deficitSize - totalSize}`));
+			tx.abort();
+			return false;
+		}
+		const keys = [];
+		while (deficitSize > 0 && metadatas.length) {
+			const index = random(0, metadatas.length - 1);
+			const metadata = metadatas[index];
+			deficitSize -= metadata.size;
+			keys.push(metadata.key);
+			metadatas.splice(index, 1);
+		}
+		await this.__remove__(tx, keys);
+		await tx.done;
+		this.__onCacheEvict__?.({ keys });
+		return true;
+	}
+};
+//#endregion
+//#region src/storage/indexed-db-storage/lfu-indexed-db-storage.ts
+var LFUIndexedDBStorage = class extends BaseIndexedDBStorage {
+	constructor(options) {
+		super(options);
+	}
+	async get(key) {
+		const entry = await super.get(key);
+		this.__onCacheGet__?.({ key });
+		return entry;
+	}
+	async set(value) {
+		await super.set(value);
+		this.__onCacheSet__?.({ key: value.key });
+	}
+	async remove(key) {
+		await super.remove(key);
+		this.__onCacheRemove__?.({ key });
+	}
+	async evict(expectSize) {
+		await this.evictExpired();
+		let deficitSize = expectSize - (await this.getSize()).free;
+		if (deficitSize <= 0) return true;
+		const tx = (await this.openDB()).transaction([
+			"metadata",
+			"response",
+			"visits"
+		], "readwrite");
+		const metadataStore = tx.objectStore("metadata");
+		let cursor = await tx.objectStore("visits").index("visitCount").openCursor();
+		const keys = [];
+		while (deficitSize > 0 && cursor) {
+			const metadata = await metadataStore.get(cursor.value.key);
+			if (!metadata) {
+				await cursor.delete();
+				cursor = await cursor.continue();
+				continue;
+			}
+			deficitSize -= metadata.size;
+			keys.push(cursor.value.key);
+			cursor = await cursor.continue();
+		}
+		if (deficitSize > 0) {
+			this.debug((log) => log(`Storage Size Not Enough, deficit size: ${deficitSize}`));
+			tx.abort();
+			return false;
+		}
+		await this.__remove__(tx, keys);
+		await tx.done;
+		this.__onCacheEvict__?.({ keys });
+		return true;
+	}
+};
+//#endregion
+//#region src/storage/indexed-db-storage/lru-indexed-db-storage.ts
+var LRUIndexedDBStorage = class extends BaseIndexedDBStorage {
+	constructor(options) {
+		super(options);
+	}
+	async get(key) {
+		const entry = await super.get(key);
+		this.__onCacheGet__?.({ key });
+		return entry;
+	}
+	async set(value) {
+		await super.set(value);
+		this.__onCacheSet__?.({ key: value.key });
+	}
+	async remove(key) {
+		await super.remove(key);
+		this.__onCacheRemove__?.({ key });
+	}
+	async evict(expectSize) {
+		await this.evictExpired();
+		let deficitSize = expectSize - (await this.getSize()).free;
+		if (deficitSize <= 0) return true;
+		const tx = (await this.openDB()).transaction([
+			"metadata",
+			"response",
+			"visits"
+		], "readwrite");
+		const metadataStore = tx.objectStore("metadata");
+		const visitsStore = tx.objectStore("visits");
+		const keys = [];
+		let cursor = await visitsStore.index("lastVisitedAt").openCursor();
+		while (deficitSize > 0 && cursor) {
+			const metadata = await metadataStore.get(cursor.value.key);
+			if (!metadata) {
+				await cursor.delete();
+				cursor = await cursor.continue();
+				continue;
+			}
+			deficitSize -= metadata.size;
+			keys.push(cursor.value.key);
+			cursor = await cursor.continue();
+		}
+		if (deficitSize > 0) {
+			this.debug((log) => log(`Storage Size Not Enough, deficit size: ${deficitSize}`));
+			tx.abort();
+			return false;
+		}
+		await this.__remove__(tx, keys);
+		await tx.done;
+		this.__onCacheEvict__?.({ keys });
+		return true;
+	}
+};
+//#endregion
+//#region src/storage/indexed-db-storage/ttl-indexed-db-storage.ts
+var TTLIndexedDBStorage = class extends BaseIndexedDBStorage {
+	constructor(options) {
+		super(options);
+	}
+	async get(key) {
+		const entry = await super.get(key);
+		this.__onCacheGet__?.({ key });
+		return entry;
+	}
+	async set(value) {
+		await super.set(value);
+		this.__onCacheSet__?.({ key: value.key });
+	}
+	async remove(key) {
+		await super.remove(key);
+		this.__onCacheRemove__?.({ key });
+	}
+	async evict(expectSize) {
+		await this.evictExpired();
+		let deficitSize = expectSize - (await this.getSize()).free;
+		if (deficitSize <= 0) return true;
+		const tx = (await this.openDB()).transaction([
+			"metadata",
+			"response",
+			"visits"
+		], "readwrite");
+		const metadataStore = tx.objectStore("metadata");
+		const keys = [];
+		let cursor = await metadataStore.index("expiredAt").openCursor();
+		while (deficitSize > 0 && cursor) {
+			const metadata = await metadataStore.get(cursor.value.key);
+			if (!metadata) {
+				await cursor.delete();
+				cursor = await cursor.continue();
+				continue;
+			}
+			deficitSize -= metadata.size;
+			keys.push(cursor.value.key);
+			cursor = await cursor.continue();
+		}
+		if (deficitSize > 0) {
+			this.debug((log) => log(`Storage Size Not Enough, deficit size: ${deficitSize}`));
+			tx.abort();
+			return false;
+		}
+		await this.__remove__(tx, keys);
+		await tx.done;
+		this.__onCacheEvict__?.({ keys });
+		return true;
+	}
+};
+//#endregion
+//#region src/storage/indexed-db-storage/indexed-db-storage.ts
+var IndexedDBStorage = class extends KeqCacheStorage {
+	constructor(options) {
+		super();
+		_defineProperty(this, "storage", void 0);
+		const eviction = options?.eviction || "lru";
+		if (eviction === "random") this.storage = new RandomIndexedDBStorage(options);
+		else if (eviction === "lfu") this.storage = new LFUIndexedDBStorage(options);
+		else if (eviction === "lru") this.storage = new LRUIndexedDBStorage(options);
+		else if (eviction === "ttl") this.storage = new TTLIndexedDBStorage(options);
+		else throw new CacheException(`Not Supported Eviction: ${String(options?.eviction)}`);
+	}
+	set(entry) {
+		return this.storage.set(entry);
+	}
+	get(key) {
+		return this.storage.get(key);
+	}
+	remove(key) {
+		return this.storage.remove(key);
+	}
+};
+//#endregion
+//#region src/storage/multi-tier-storage/multi-tier-storage.ts
+/**
+* @en Multi-tier cache storage that manages multiple KeqCacheStorage instances in tiers
+* @zh 多层缓存存储，管理多个分层的 KeqCacheStorage 实例
+*/
+var MultiTierStorage = class extends KeqCacheStorage {
+	/**
+	* @param storages Array of storage instances ordered by performance (fastest first)
+	* @zh 按性价比排序的存储实例数组，排在前面的成本低，排在后面的成本高
+	*/
+	constructor(options) {
+		super();
+		_defineProperty(this, "storages", void 0);
+		if (!options.tiers || options.tiers.length === 0) throw new Error("At least one storage instance is required");
+		this.storages = [...options.tiers];
+	}
+	/**
+	* @en Get cache entry, searching from lowest to highest tier
+	* @zh 获取缓存条目，从最底层到高层依次搜索
+	*/
+	async get(key) {
+		for (let i = 0; i < this.storages.length; i++) {
+			const entry = await this.storages[i].get(key);
+			if (entry) {
+				if (i > 0) await this.syncToLowerTiers(entry, i);
+				return entry;
+			}
+		}
+	}
+	/**
+	* @en Set cache entry to all tiers concurrently
+	* @zh 并发写入所有层的缓存
+	*/
+	async set(entry) {
+		const promises = this.storages.map(async (storage) => storage.set(entry));
+		await Promise.all(promises);
+	}
+	/**
+	* @en Remove cache entry from all tiers
+	* @zh 从所有层删除缓存条目
+	*/
+	async remove(key) {
+		const promises = this.storages.map(async (storage) => storage.remove(key));
+		await Promise.all(promises);
+	}
+	/**
+	* @en Sync cache entry to all lower tiers (tiers with index < currentTierIndex)
+	* @zh 将缓存条目同步到所有低层存储（索引小于当前层的存储）
+	*/
+	async syncToLowerTiers(entry, currentTierIndex) {
+		const lowerTierStorages = this.storages.slice(0, currentTierIndex);
+		if (lowerTierStorages.length === 0) return;
+		const promises = lowerTierStorages.map(async (storage) => storage.set(entry.clone()));
+		try {
+			await Promise.all(promises);
+		} catch (error) {
+			console.warn("Failed to sync cache entry to lower tiers:", error);
+		}
+	}
+};
+//#endregion
+//#region src/storage/tier-storage/tier-storage.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
+*/
+var TierStorage = class extends MultiTierStorage {
+	constructor(options) {
+		const memoryStorage = options?.memory instanceof MemoryStorage ? options.memory : new MemoryStorage(options?.memory);
+		const indexedDBStorage = options?.indexedDB instanceof IndexedDBStorage ? options.indexedDB : new IndexedDBStorage(options?.indexedDB);
+		super({ tiers: [memoryStorage, indexedDBStorage] });
+	}
+};
+//#endregion
+export { Eviction, IndexedDBStorage, KeqCacheStorage, MemoryStorage, MultiTierStorage, Size, Strategy, TierStorage, cache };
+
+//# sourceMappingURL=index.mjs.map