cachimbo 0.0.1

package/dist/index.cjs

@@ -0,0 +1,1125 @@
+let lru_cache = require("lru-cache");
+let __isaacs_ttlcache = require("@isaacs/ttlcache");
+
+//#region src/base/index.ts
+/**
+* The base implementation of a cache.
+*
+* This class only requires subclasses to implement {@link ICache#get}, {@link ICache#set} and {@link ICache#delete}.
+* All other methods fall back into these three.
+*/
+var BaseCache = class {
+	name;
+	logger;
+	constructor(options) {
+		this.name = options.name;
+		this.logger = options.logger;
+	}
+	async getOrLoad(key, load, options) {
+		let data = await this.get(key);
+		if (data !== null) {
+			this.logger?.debug(this.name, "[getOrLoad] Returning from cache.", "key =", key);
+			return data;
+		}
+		this.logger?.debug(this.name, "[getOrLoad] Refreshing the cache...", "key =", key);
+		data = await load();
+		await this.set(key, data, options);
+		return data;
+	}
+	async getMany(keys) {
+		this.logger?.debug(this.name, "[getMany] Reading all keys in parallel...", "keys =", keys);
+		return Object.fromEntries(await Promise.all(keys.map(async (key) => [key, await this.get(key)])));
+	}
+	async setMany(data, options) {
+		this.logger?.debug(this.name, "[setMany] Writing all keys in parallel...", "data =", data);
+		await Promise.all(Object.entries(data).map(([key, value]) => this.set(key, value, options)));
+	}
+	async deleteMany(keys) {
+		this.logger?.debug(this.name, "[deleteMany] Deleting all keys in parallel...", "keys =", keys);
+		await Promise.all(keys.map((key) => this.delete(key)));
+	}
+};
+
+//#endregion
+//#region src/local/lru/index.ts
+/**
+* An in-memory cache implementation of a Least-Recently-Used cache eviction algorithm.
+*
+* It allows setting an expiration time and a limit of cached items.
+*
+* Once the limit of items is reached, the least recently used items will be purged.
+*/
+var LocalLRUCache = class extends BaseCache {
+	cache;
+	shouldUseFetch;
+	constructor(options = {}) {
+		super(options);
+		if ("cache" in options) {
+			this.cache = options.cache;
+			this.shouldUseFetch = options.shouldUseFetch;
+		} else {
+			this.cache = new lru_cache.LRUCache({
+				ttl: options.ttl ? options.ttl * 1e3 : void 0,
+				max: options.max || 1e4,
+				ttlAutopurge: false,
+				fetchMethod: (_key, _staleValue, options$1) => options$1.context()
+			});
+			this.shouldUseFetch = true;
+		}
+	}
+	async get(key) {
+		this.logger?.debug(this.name, "[get]", "key =", key);
+		const data = this.cache.get(key);
+		return data === void 0 ? null : data;
+	}
+	getOrLoad(key, load, options) {
+		if (!this.shouldUseFetch) return super.getOrLoad(key, load, options);
+		this.logger?.debug(this.name, "[getOrLoad] Running LRUCache's fetch...", "key =", key);
+		const ttl = options?.ttl;
+		return this.cache.fetch(key, {
+			context: load,
+			ttl: ttl ? ttl * 1e3 : void 0
+		});
+	}
+	async set(key, value, options) {
+		this.logger?.debug(this.name, "[set]", "key =", key);
+		const ttl = options?.ttl;
+		this.cache.set(key, value, { ttl: ttl ? ttl * 1e3 : void 0 });
+	}
+	async delete(key) {
+		this.logger?.debug(this.name, "[delete]", "key =", key);
+		this.cache.delete(key);
+	}
+};
+
+//#endregion
+//#region src/local/ttl/index.ts
+/**
+* An in-memory cache implementation that allows setting an expiration time and a limit of cached items.
+*
+* Once the limit of items is reached, the soonest expiring items will be purged.
+*/
+var LocalTTLCache = class extends BaseCache {
+	cache;
+	constructor(options = {}) {
+		super(options);
+		if ("cache" in options) this.cache = options.cache;
+		else this.cache = new __isaacs_ttlcache.TTLCache({
+			max: options.max,
+			ttl: options.ttl ? options.ttl * 1e3 : void 0
+		});
+	}
+	async get(key) {
+		this.logger?.debug(this.name, "[get]", "key =", key);
+		const data = this.cache.get(key);
+		return data === void 0 ? null : data;
+	}
+	async set(key, value, options) {
+		this.logger?.debug(this.name, "[set]", "key =", key);
+		const ttl = options?.ttl;
+		this.cache.set(key, value, { ttl: ttl ? ttl * 1e3 : void 0 });
+	}
+	async delete(key) {
+		this.logger?.debug(this.name, "[delete]", "key =", key);
+		this.cache.delete(key);
+	}
+};
+
+//#endregion
+//#region src/local/map/index.ts
+/**
+* A simple in-memory cache implementation based on {@link Map}.
+*
+* It ignores expiration times, but a limit of cached items can be set.
+*
+* Once the limit of items is reached, the first inserted keys will be purged.
+*/
+var LocalMapCache = class extends BaseCache {
+	cache;
+	max;
+	constructor(options = {}) {
+		super(options);
+		this.cache = options.cache ?? /* @__PURE__ */ new Map();
+		this.max = options.max ?? Infinity;
+	}
+	async get(key) {
+		this.logger?.debug(this.name, "[get]", "key =", key);
+		const data = this.cache.get(key);
+		return data === void 0 ? null : data;
+	}
+	async set(key, value, options) {
+		this.logger?.debug(this.name, "[set]", "key =", key);
+		if (this.cache.size >= this.max && !this.cache.has(key)) this.evict(1);
+		this.cache.set(key, value);
+	}
+	async delete(key) {
+		this.logger?.debug(this.name, "[delete]", "key =", key);
+		this.cache.delete(key);
+	}
+	async setMany(data, options) {
+		this.logger?.debug(this.name, "[setMany]", "data =", data);
+		const entries = Object.entries(data);
+		const newEntries = entries.filter(([key]) => !this.cache.has(key)).length;
+		if (this.cache.size + newEntries > this.max) this.evict(this.cache.size + newEntries - this.max);
+		for (const [key, value] of entries) this.cache.set(key, value);
+	}
+	clear() {
+		this.logger?.debug(this.name, "[clear]");
+		this.cache.clear();
+	}
+	evict(length) {
+		const keys = this.cache.keys();
+		for (let i = 0; i < length; i++) {
+			const key = keys.next();
+			if (key.done) break;
+			this.logger?.debug(this.name, "[evict]", "key = ", key);
+			this.cache.delete(key.value);
+		}
+	}
+};
+
+//#endregion
+//#region src/local/noop/index.ts
+/**
+* A cache implementation that does nothing.
+* It's useful for disabling cache.
+*
+* @example
+* ```ts
+* const cache = isCacheEnabled ? new LocalTTLCache() : new NoOpCache();
+* ```
+*/
+var NoOpCache = class {
+	constructor() {}
+	async get(key) {
+		return null;
+	}
+	async getMany(keys) {
+		return {};
+	}
+	getOrLoad(key, load, options) {
+		return load();
+	}
+	async set(key, value, options) {}
+	async setMany(data, options) {}
+	async delete(key) {}
+	async deleteMany(keys) {}
+};
+
+//#endregion
+//#region src/remote/ioredis/index.ts
+/**
+* A Redis cache implementation using ioredis
+*/
+var IORedisCache = class extends BaseCache {
+	client;
+	defaultTTL;
+	isMSETEXSupported;
+	constructor(options) {
+		super(options);
+		this.client = options.client;
+		this.defaultTTL = options.defaultTTL;
+		this.isMSETEXSupported = options.isMSETEXSupported;
+	}
+	async get(key) {
+		this.logger?.debug(this.name, "[get] Running \"GET\" command...", "key =", key);
+		const raw = await this.client.get(key);
+		return raw ? JSON.parse(raw) : null;
+	}
+	async set(key, value, options) {
+		this.logger?.debug(this.name, "[set] Running \"SET\" command...", "key =", key);
+		const ttl = options?.ttl ?? this.defaultTTL;
+		const raw = JSON.stringify(value);
+		if (ttl) await this.client.set(key, raw, "EX", ttl);
+		else await this.client.set(key, raw);
+	}
+	async delete(key) {
+		this.logger?.debug(this.name, "[delete] Running \"DEL\" command...", "key =", key);
+		await this.client.del(key);
+	}
+	async getMany(keys) {
+		this.logger?.debug(this.name, "[getMany] Running \"MGET\" command...", "keys =", keys);
+		const values = await this.client.mget(keys);
+		const data = {};
+		for (let i = 0; i < keys.length; i++) {
+			const value = values[i];
+			data[keys[i]] = value ? JSON.parse(value) : null;
+		}
+		return data;
+	}
+	async setMany(data, options) {
+		if (!this.isMSETEXSupported) return super.setMany(data, options);
+		this.logger?.debug(this.name, "[setMany] Running \"MSETEX\" command...", "data =", data);
+		const entries = Object.entries(data);
+		const ttl = options?.ttl ?? this.defaultTTL;
+		const raw = entries.flatMap(([key, value]) => [key, JSON.stringify(value)]);
+		await this.client.call("MSETEX", entries.length, ...raw, ...ttl ? ["EX", ttl] : []);
+	}
+	async deleteMany(keys) {
+		this.logger?.debug(this.name, "[deleteMany] Running \"DEL\" command...", "keys =", keys);
+		await this.client.del(keys);
+	}
+};
+
+//#endregion
+//#region src/remote/redis/index.ts
+/**
+* A Redis cache implementation using node-redis
+*/
+var RedisCache = class extends BaseCache {
+	client;
+	defaultTTL;
+	isMSETEXSupported;
+	constructor(options) {
+		super(options);
+		this.client = options.client;
+		this.defaultTTL = options.defaultTTL;
+		this.isMSETEXSupported = options.isMSETEXSupported;
+	}
+	async get(key) {
+		this.logger?.debug(this.name, "[get] Running \"GET\" command...", "key =", key);
+		const raw = await this.client.get(key);
+		return raw ? JSON.parse(raw) : null;
+	}
+	async set(key, value, options) {
+		this.logger?.debug(this.name, "[set] Running \"SET\" command...", "key =", key);
+		const ttl = options?.ttl ?? this.defaultTTL;
+		await this.client.set(key, JSON.stringify(value), { expiration: ttl ? {
+			type: "EX",
+			value: ttl
+		} : void 0 });
+	}
+	async delete(key) {
+		this.logger?.debug(this.name, "[delete] Running \"DEL\" command...", "key =", key);
+		await this.client.del(key);
+	}
+	async getMany(keys) {
+		this.logger?.debug(this.name, "[getMany] Running \"MGET\" command...", "keys =", keys);
+		const values = await this.client.mGet(keys);
+		const data = {};
+		for (let i = 0; i < keys.length; i++) {
+			const value = values[i];
+			data[keys[i]] = value ? JSON.parse(value) : null;
+		}
+		return data;
+	}
+	async setMany(data, options) {
+		if (!this.isMSETEXSupported) return super.setMany(data, options);
+		this.logger?.debug(this.name, "[setMany] Running \"MSETEX\" command...", "data =", data);
+		const raw = [];
+		const ttl = options?.ttl ?? this.defaultTTL;
+		for (const [key, value] of Object.entries(data)) raw.push([key, JSON.stringify(value)]);
+		await this.client.mSetEx(raw, { expiration: ttl ? {
+			type: "EX",
+			value: ttl
+		} : void 0 });
+	}
+	async deleteMany(keys) {
+		this.logger?.debug(this.name, "[deleteMany] Running \"DEL\" command...", "keys =", keys);
+		await this.client.del(keys);
+	}
+};
+
+//#endregion
+//#region src/remote/valkey-glide/index.ts
+/**
+* A Valkey cache implementation using @valkey/valkey-glide
+*/
+var ValkeyGlideCache = class extends BaseCache {
+	client;
+	defaultTTL;
+	constructor(options) {
+		super(options);
+		this.client = options.client;
+		this.defaultTTL = options.defaultTTL;
+	}
+	async get(key) {
+		this.logger?.debug(this.name, "[get] Running \"GET\" command...", "key =", key);
+		const raw = await this.client.get(key);
+		return raw ? JSON.parse(raw.toString()) : null;
+	}
+	async set(key, value, options) {
+		this.logger?.debug(this.name, "[set] Running \"SET\" command...", "key =", key);
+		const ttl = options?.ttl ?? this.defaultTTL;
+		await this.client.set(key, JSON.stringify(value), { expiry: ttl ? {
+			type: "EX",
+			count: ttl
+		} : void 0 });
+	}
+	async delete(key) {
+		this.logger?.debug(this.name, "[delete] Running \"DEL\" command...", "key =", key);
+		await this.client.del([key]);
+	}
+	async getMany(keys) {
+		this.logger?.debug(this.name, "[getMany] Running \"MGET\" command...", "keys =", keys);
+		const values = await this.client.mget(keys);
+		const data = {};
+		for (let i = 0; i < keys.length; i++) {
+			const value = values[i];
+			data[keys[i]] = value ? JSON.parse(value.toString()) : null;
+		}
+		return data;
+	}
+	async deleteMany(keys) {
+		this.logger?.debug(this.name, "[deleteMany] Running \"DEL\" command...", "keys =", keys);
+		await this.client.del(keys);
+	}
+};
+
+//#endregion
+//#region src/remote/memcache/index.ts
+/**
+* A Memcached cache implementation using Memcache
+*/
+var MemcacheCache = class extends BaseCache {
+	client;
+	defaultTTL;
+	constructor(options) {
+		super(options);
+		this.client = options.client;
+		this.defaultTTL = options.defaultTTL;
+	}
+	async get(key) {
+		this.logger?.debug(this.name, "[get] Running \"get\" command...", "key =", key);
+		const raw = await this.client.get(key);
+		return raw ? JSON.parse(raw) : null;
+	}
+	async set(key, value, options) {
+		this.logger?.debug(this.name, "[set] Running \"set\" command...", "key =", key);
+		await this.client.set(key, JSON.stringify(value), options?.ttl ?? this.defaultTTL);
+	}
+	async delete(key) {
+		this.logger?.debug(this.name, "[delete] Running \"delete\" command...", "key =", key);
+		await this.client.delete(key);
+	}
+	async getMany(keys) {
+		this.logger?.debug(this.name, "[getMany] Running \"get\" command...", "keys =", keys);
+		const raw = await this.client.gets(keys);
+		const data = {};
+		raw.forEach((value, key) => {
+			data[key] = value ? JSON.parse(value) : null;
+		});
+		return data;
+	}
+};
+
+//#endregion
+//#region src/remote/memjs/index.ts
+/**
+* A Memcached cache implementation using MemJS
+*/
+var MemJSCache = class extends BaseCache {
+	client;
+	defaultTTL;
+	constructor(options) {
+		super(options);
+		this.client = options.client;
+		this.defaultTTL = options.defaultTTL;
+	}
+	async get(key) {
+		this.logger?.debug(this.name, "[get] Running \"get\" command...", "key =", key);
+		const { value } = await this.client.get(key);
+		return value ? JSON.parse(value.toString("utf8")) : null;
+	}
+	async set(key, value, options) {
+		this.logger?.debug(this.name, "[set] Running \"set\" command...", "key =", key);
+		await this.client.set(key, JSON.stringify(value), { expires: options?.ttl ?? this.defaultTTL });
+	}
+	async delete(key) {
+		this.logger?.debug(this.name, "[delete] Running \"delete\" command...", "key =", key);
+		await this.client.delete(key);
+	}
+};
+
+//#endregion
+//#region src/remote/workers-kv/index.ts
+/**
+* A Cloudflare Workers KV cache implementation.
+*/
+var WorkersKVCache = class extends BaseCache {
+	kv;
+	edgeCacheTTL;
+	constructor(options) {
+		super(options);
+		this.kv = options.kv;
+		this.edgeCacheTTL = options.edgeCacheTTL;
+	}
+	get(key) {
+		return this.kv.get(key, {
+			type: "json",
+			cacheTtl: this.edgeCacheTTL
+		});
+	}
+	set(key, value, options = {}) {
+		return this.kv.put(key, JSON.stringify(value), { expirationTtl: options.ttl });
+	}
+	delete(key) {
+		return this.kv.delete(key);
+	}
+	async getMany(keys) {
+		const data = await this.kv.get(keys, { type: "json" });
+		return Object.fromEntries(data);
+	}
+};
+
+//#endregion
+//#region src/remote/keyv/index.ts
+var KeyvCache = class extends BaseCache {
+	keyv;
+	constructor(options) {
+		super(options);
+		this.keyv = options.keyv;
+	}
+	async get(key) {
+		const result = await this.keyv.get(key);
+		return result === void 0 ? null : result;
+	}
+	async set(key, value, options) {
+		await this.keyv.set(key, value, options?.ttl);
+	}
+	async delete(key) {
+		await this.keyv.delete(key);
+	}
+	async getMany(keys) {
+		const data = await this.keyv.getMany(keys);
+		const result = {};
+		for (let i = 0; i < keys.length; i++) result[keys[i]] = data[i] === void 0 ? null : data[i];
+		return result;
+	}
+	async setMany(data, options) {
+		const ttl = options?.ttl;
+		await this.keyv.setMany(Object.entries(data).map(([key, value]) => ({
+			key,
+			value,
+			ttl
+		})));
+	}
+	async deleteMany(keys) {
+		await this.keyv.deleteMany(keys);
+	}
+};
+
+//#endregion
+//#region src/layers/async-lazy/index.ts
+/**
+* A cache layer that initializes the underlying cache asynchronously.
+*
+* This layer can be used to connect to an external cache with the cache methods already available.
+*
+* This layer can also be used to lazily initialize the cache only when it's actually needed.
+*
+* @example
+* ```ts
+* const cache = new AsyncCache({
+*   factory: async () => {
+*     const redisClient = await createClient({
+*       url: "redis://user:password@localhost:6380",
+*     });
+*
+*     return new RedisCache({ client: redisClient });
+*   },
+*   lazy: true,
+* });
+*
+* cache.get("key")
+*   .then(result => console.log('redis was connected and read the key:', value));
+* ```
+*/
+var AsyncLazyCache = class {
+	factory;
+	cache = null;
+	constructor(options) {
+		this.factory = options.factory;
+		if (!options.lazy) this.cache = Promise.resolve(this.factory());
+	}
+	async get(key) {
+		return (await this.resolveCache()).get(key);
+	}
+	async getOrLoad(key, load, options) {
+		return (await this.resolveCache()).getOrLoad(key, load, options);
+	}
+	async set(key, value, options) {
+		return (await this.resolveCache()).set(key, value, options);
+	}
+	async delete(key) {
+		return (await this.resolveCache()).delete(key);
+	}
+	async getMany(keys) {
+		return (await this.resolveCache()).getMany(keys);
+	}
+	async setMany(data, options) {
+		return (await this.resolveCache()).setMany(data, options);
+	}
+	async deleteMany(keys) {
+		return (await this.resolveCache()).deleteMany(keys);
+	}
+	/**
+	* Gets the underlying cache, initializing it if not already initialized.
+	*/
+	resolveCache() {
+		if (!this.cache) this.cache = Promise.resolve(this.factory());
+		return this.cache;
+	}
+};
+
+//#endregion
+//#region src/layers/coalescing/index.ts
+/**
+* A cache strategy layer that deduplicates parallel requests into a single request.
+*
+* This strategy can prevent the Thundering Herd problem as all parallel requests will be coalesced into one.
+*/
+var CoalescingCache = class {
+	ongoingRequests = /* @__PURE__ */ new Map();
+	cache;
+	name;
+	logger;
+	constructor(options) {
+		this.cache = options.cache;
+		this.name = options.name;
+		this.logger = options.logger;
+	}
+	get(key) {
+		const ongoingRequest = this.ongoingRequests.get(key);
+		if (ongoingRequest) {
+			this.logger?.debug(this.name, "[get] Returning ongoing request...", "key =", key);
+			return ongoingRequest.promise;
+		}
+		this.logger?.debug(this.name, "[get] Reading from underlying cache...", "key =", key);
+		const promise = this.cache.get(key);
+		this.ongoingRequests.set(key, {
+			promise,
+			type: "get"
+		});
+		return promise.finally(() => this.ongoingRequests.delete(key));
+	}
+	async getOrLoad(key, load, options) {
+		const ongoingRequest = this.ongoingRequests.get(key);
+		if (!ongoingRequest) {
+			this.logger?.debug(this.name, "[getOrLoad] Reading from the underlying cache...", "key =", key);
+			const promise$1 = this.cache.getOrLoad(key, load, options);
+			this.ongoingRequests.set(key, {
+				promise: promise$1,
+				type: "getOrLoad"
+			});
+			return promise$1.finally(() => this.ongoingRequests.delete(key));
+		}
+		let request = await ongoingRequest.promise;
+		if (request !== null || ongoingRequest.type === "getOrLoad") {
+			this.logger?.debug(this.name, "[getOrLoad] Read from an ongoing request.", "key =", key);
+			return request;
+		}
+		this.logger?.debug(this.name, "[getOrLoad] Refreshing the cache...", "key =", key);
+		const promise = load();
+		this.ongoingRequests.set(key, {
+			promise,
+			type: "getOrLoad"
+		});
+		try {
+			request = await promise;
+			if (request !== null) await this.cache.set(key, request, options);
+		} finally {
+			this.ongoingRequests.delete(key);
+		}
+		return request;
+	}
+	set(key, value, options) {
+		this.logger?.debug(this.name, "[set]", "key =", key);
+		const promise = this.cache.set(key, value, options);
+		this.ongoingRequests.set(key, {
+			promise: promise.then(() => value),
+			type: "getOrLoad"
+		});
+		return promise.finally(() => this.ongoingRequests.delete(key));
+	}
+	async delete(key) {
+		this.logger?.debug(this.name, "[delete]", "key =", key);
+		try {
+			this.ongoingRequests.set(key, {
+				type: "get",
+				promise: Promise.resolve(null)
+			});
+			await this.cache.delete(key);
+		} finally {
+			this.ongoingRequests.delete(key);
+		}
+	}
+	async getMany(keys) {
+		const items = [];
+		const remainingKeys = [];
+		for (const key of keys) {
+			const ongoingRequest = this.ongoingRequests.get(key);
+			if (ongoingRequest) items.push([key, ongoingRequest.promise]);
+			else remainingKeys.push(key);
+		}
+		this.logger?.debug(this.name, "[getMany]", items.length, "ongoing requests found, reading", remainingKeys.length, "resources.", "keys =", keys);
+		if (remainingKeys.length > 0) {
+			const promise = this.cache.getMany(remainingKeys);
+			for (const key of remainingKeys) {
+				const itemPromise = promise.then((data) => data[key]).finally(() => this.ongoingRequests.delete(key));
+				this.ongoingRequests.set(key, {
+					promise: itemPromise,
+					type: "get"
+				});
+				items.push([key, itemPromise]);
+			}
+		}
+		return Object.fromEntries(await Promise.all(items.map(async ([key, promise]) => [key, await promise])));
+	}
+	setMany(data, options) {
+		this.logger?.debug(this.name, "[setMany]", "data =", data);
+		const promise = this.cache.setMany(data, options);
+		for (const [key, value] of Object.entries(data)) this.ongoingRequests.set(key, {
+			promise: promise.then(() => value).finally(() => this.ongoingRequests.delete(key)),
+			type: "getOrLoad"
+		});
+		return promise;
+	}
+	async deleteMany(keys) {
+		this.logger?.debug(this.name, "[deleteMany]", "keys =", keys);
+		try {
+			for (const key of keys) this.ongoingRequests.set(key, {
+				type: "get",
+				promise: Promise.resolve(null)
+			});
+			await this.cache.deleteMany(keys);
+		} finally {
+			for (const key of keys) this.ongoingRequests.delete(key);
+		}
+	}
+};
+
+//#endregion
+//#region src/layers/jittering/index.ts
+/**
+* A cache layer that adds a random jitter to the TTL of cached items to prevent cache stampedes.
+*
+* This layer is useful in scenarios where many cached items expire simultaneously, causing a sudden surge of requests to the underlying data source.
+*/
+var JitteringCache = class {
+	cache;
+	defaultTTL;
+	maxJitterTTL;
+	constructor(options) {
+		this.cache = options.cache;
+		this.defaultTTL = options.defaultTTL;
+		this.maxJitterTTL = options.maxJitterTTL;
+	}
+	get(key) {
+		return this.cache.get(key);
+	}
+	getOrLoad(key, load, options = {}) {
+		return this.cache.getOrLoad(key, load, this.jitterTTL(options));
+	}
+	set(key, value, options) {
+		return this.cache.set(key, value, this.jitterTTL(options));
+	}
+	delete(key) {
+		return this.cache.delete(key);
+	}
+	getMany(keys) {
+		return this.cache.getMany(keys);
+	}
+	setMany(data, options) {
+		return this.cache.setMany(data, this.jitterTTL(options));
+	}
+	deleteMany(keys) {
+		return this.cache.deleteMany(keys);
+	}
+	jitterTTL(options = {}) {
+		const ttl = options.ttl ?? this.defaultTTL;
+		const jitter = Math.random() * this.maxJitterTTL;
+		return {
+			...options,
+			ttl: ttl + jitter
+		};
+	}
+};
+
+//#endregion
+//#region src/layers/key-transforming/index.ts
+/**
+* A cache layer that changes keys before passing them to the underlying cache.
+*
+* This layer can be used to:
+* - Create namespaced caches, avoiding conflicts with shared cache servers.
+* - Add a version number, allowing schema changes without causing incompatibility.
+* - Implement any other key transformations, such as normalizing or hashing.
+*/
+var KeyTransformingCache = class {
+	cache;
+	transform;
+	constructor(options) {
+		this.cache = options.cache;
+		if ("transform" in options) this.transform = options.transform;
+		else {
+			const prefix = options.prefix || "";
+			const suffix = options.suffix || "";
+			this.transform = (key) => `${prefix}${key}${suffix}`;
+		}
+	}
+	get(key) {
+		return this.cache.get(this.transform(key));
+	}
+	getOrLoad(key, load, options) {
+		return this.cache.getOrLoad(this.transform(key), load, options);
+	}
+	set(key, value, options) {
+		return this.cache.set(this.transform(key), value, options);
+	}
+	delete(key) {
+		return this.cache.delete(this.transform(key));
+	}
+	async getMany(keys) {
+		const transformedKeys = keys.map((key) => this.transform(key));
+		const data = await this.cache.getMany(transformedKeys);
+		return Object.fromEntries(Object.entries(data).map(([transformedKey, value]) => [keys[transformedKeys.indexOf(transformedKey)], value]));
+	}
+	setMany(data, options) {
+		return this.cache.setMany(Object.fromEntries(Object.entries(data).map(([key, value]) => [this.transform(key), value])), options);
+	}
+	deleteMany(keys) {
+		return this.cache.deleteMany(keys.map((key) => this.transform(key)));
+	}
+};
+
+//#endregion
+//#region src/layers/swr/index.ts
+/**
+* A cache strategy that returns stale resources immediately while it refreshes the cache in background.
+*
+* This is an implementation of the Stale-While-Revalidate algorithm.
+*
+* This strategy is only effective when calling {@link ICache#getOrLoad}.
+*/
+var SWRCache = class {
+	revalidating = /* @__PURE__ */ new Map();
+	cache;
+	name;
+	logger;
+	defaultTTL;
+	staleTTL;
+	constructor(options) {
+		this.cache = options.cache;
+		this.name = options.name;
+		this.logger = options.logger;
+		this.defaultTTL = options.defaultTTL;
+		this.staleTTL = options.staleTTL;
+	}
+	async get(key) {
+		this.logger?.debug(this.name, "[get]", "key =", key);
+		const item = await this.cache.get(key);
+		return item ? item.data : null;
+	}
+	async getOrLoad(key, load, options = {}) {
+		this.logger?.debug(this.name, "[getOrLoad]", "key =", key);
+		const ttl = options.ttl || this.defaultTTL;
+		const cacheOptions = {
+			...options,
+			ttl: ttl + this.staleTTL
+		};
+		const loadItem = async () => ({
+			data: await load(),
+			expiresAt: Date.now() + ttl * 1e3
+		});
+		const item = await this.cache.getOrLoad(key, loadItem, cacheOptions);
+		if (item && item.expiresAt < Date.now() && !this.revalidating.has(key)) {
+			this.logger?.debug(this.name, "[getOrLoad] Refreshing stale resource in background...", "key =", key);
+			const promise = loadItem().then((newItem) => this.cache.set(key, newItem, cacheOptions)).finally(() => this.revalidating.delete(key));
+			this.revalidating.set(key, promise);
+		}
+		return item.data;
+	}
+	set(key, value, options = {}) {
+		this.logger?.debug(this.name, "[set]", "key =", key);
+		const ttl = options.ttl || this.defaultTTL;
+		const item = {
+			data: value,
+			expiresAt: Date.now() + ttl * 1e3
+		};
+		const cacheOptions = {
+			...options,
+			ttl: ttl + this.staleTTL
+		};
+		return this.cache.set(key, item, cacheOptions);
+	}
+	delete(key) {
+		this.logger?.debug(this.name, "[delete]", "key =", key);
+		return this.cache.delete(key);
+	}
+	async getMany(keys) {
+		this.logger?.debug(this.name, "[getMany]", "keys =", keys);
+		const data = await this.cache.getMany(keys);
+		const items = {};
+		for (const [key, value] of Object.entries(data)) items[key] = value ? value.data : null;
+		return items;
+	}
+	setMany(data, options = {}) {
+		this.logger?.debug(this.name, "[setMany]", "data =", data);
+		const ttl = options.ttl || this.defaultTTL;
+		const items = {};
+		for (const [key, value] of Object.entries(data)) items[key] = {
+			data: value,
+			expiresAt: Date.now() + ttl * 1e3
+		};
+		return this.cache.setMany(items, {
+			...options,
+			ttl: ttl + this.staleTTL
+		});
+	}
+	deleteMany(keys) {
+		this.logger?.debug(this.name, "[deleteMany]", "keys =", keys);
+		return this.cache.deleteMany(keys);
+	}
+};
+
+//#endregion
+//#region src/layers/tiered/index.ts
+/**
+* A cache strategy layer that implements multi-level caching
+*
+* The objective of a tiered cache is to minimize latency while still having the benefits of a larger, shared cache.
+* This is done by having the first tier being an in-memory cache (such as {@link LocalTTLCache}) that stores a small amount of items with a short TTL,
+* and the second tier being an external cache (such as {@link RedisCache}) that stores a lot more items and may have a longer TTL.
+*
+* This strategy is similarly known as Cache Hierarchy, CPU cache or L1/L2/L3 cache.
+*/
+var TieredCache = class extends BaseCache {
+	tiers;
+	constructor(options) {
+		super(options);
+		this.tiers = options.tiers;
+	}
+	async get(key) {
+		const next = (i) => {
+			this.logger?.debug(this.name, "[get] Reading from tier =", i, "key =", key);
+			const tier = this.tiers[i];
+			if (i === this.tiers.length - 1) return tier.cache.get(key);
+			return tier.cache.getOrLoad(key, () => next(i + 1), tier.options);
+		};
+		return next(0);
+	}
+	async getOrLoad(key, load, options) {
+		const next = (i) => {
+			this.logger?.debug(this.name, "[getOrLoad] Reading from tier =", i, "key =", key);
+			const tier = this.tiers[i];
+			if (i === this.tiers.length - 1) return tier.cache.getOrLoad(key, load, options || tier.options);
+			return tier.cache.getOrLoad(key, () => next(i + 1), tier.options);
+		};
+		return next(0);
+	}
+	async set(key, value, options) {
+		this.logger?.debug(this.name, "[set] Writing to all tiers in parallel...", "key =", key);
+		await Promise.all(this.tiers.map((tier, i) => {
+			const isLastTier = i === this.tiers.length - 1;
+			return tier.cache.set(key, value, isLastTier ? options || tier.options : tier.options);
+		}));
+	}
+	async delete(key) {
+		this.logger?.debug(this.name, "[delete] Deleting from all tiers in parallel...", "key =", key);
+		await Promise.all(this.tiers.map((tier) => tier.cache.delete(key)));
+	}
+	async getMany(keys) {
+		const next = async (i, remainingKeys) => {
+			this.logger?.debug(this.name, "[getMany] Reading from tier =", i, "keys =", keys);
+			const tier = this.tiers[i];
+			const isLastTier = i === this.tiers.length - 1;
+			const items = await tier.cache.getMany(remainingKeys);
+			remainingKeys = Object.entries(items).filter(([, value]) => value === null || value === void 0).map(([key]) => key);
+			if (isLastTier || remainingKeys.length === 0) return items;
+			const nextItems = await next(i + 1, remainingKeys);
+			const backfillItems = Object.entries(nextItems).filter(([, value]) => value !== null && value !== void 0);
+			if (backfillItems.length > 0) await tier.cache.setMany(Object.fromEntries(backfillItems), tier.options);
+			return {
+				...items,
+				...nextItems
+			};
+		};
+		return next(0, keys);
+	}
+	async setMany(data, options) {
+		this.logger?.debug(this.name, "[setMany] Writing to all tiers in parallel...", "data =", data);
+		await Promise.all(this.tiers.map((tier, i) => {
+			const isLastTier = i === this.tiers.length - 1;
+			return tier.cache.setMany(data, isLastTier ? options || tier.options : tier.options);
+		}));
+	}
+	async deleteMany(keys) {
+		this.logger?.debug(this.name, "[deleteMany] Deleting from all tiers in parallel...", "keys =", keys);
+		await Promise.all(this.tiers.map((tier) => tier.cache.deleteMany(keys)));
+	}
+};
+
+//#endregion
+//#region src/layers/metrics/index.ts
+/**
+* A cache layer that collects metrics from each cache call.
+*
+* This can be useful to measure the cache effectiveness
+*/
+var MetricsCollectingCache = class {
+	cache;
+	logger;
+	name;
+	countMetrics = {
+		missCount: 0,
+		hitCount: 0,
+		loadCount: 0,
+		setCount: 0,
+		deleteCount: 0
+	};
+	totalTimeMetrics = {
+		missTime: 0,
+		hitTime: 0,
+		loadTime: 0,
+		setTime: 0,
+		deleteTime: 0
+	};
+	constructor(options) {
+		this.cache = options.cache;
+		this.logger = options.logger;
+		this.name = options.name;
+	}
+	async get(key) {
+		const startAt = performance.now();
+		const data = await this.cache.get(key);
+		const time = performance.now() - startAt;
+		if (data === null) {
+			this.countMetrics.missCount++;
+			this.totalTimeMetrics.missTime += time;
+			this.logger?.debug(this.name, "[get] Cache miss.", "key =", key, "timeMS =", time);
+		} else {
+			this.countMetrics.hitCount++;
+			this.totalTimeMetrics.hitTime += time;
+			this.logger?.debug(this.name, "[get] Cache hit.", "key =", key, "timeMS =", time);
+		}
+		return data;
+	}
+	async getOrLoad(key, load, options) {
+		let didTriggerLoad = false;
+		let loadFinishAt = 0;
+		const loadMiddleware = () => {
+			const missFinishAt = performance.now();
+			this.countMetrics.missCount++;
+			this.totalTimeMetrics.missTime += missFinishAt - startAt;
+			didTriggerLoad = true;
+			this.logger?.debug(this.name, "[getOrLoad] Cache refresh.", "key =", key);
+			const loadStartAt = performance.now();
+			return load().finally(() => {
+				loadFinishAt = performance.now();
+				this.countMetrics.loadCount++;
+				this.totalTimeMetrics.loadTime += loadFinishAt - loadStartAt;
+			});
+		};
+		let startAt = performance.now();
+		const data = await this.cache.getOrLoad(key, loadMiddleware, options);
+		if (!didTriggerLoad) {
+			const hitFinishedAt = performance.now();
+			this.countMetrics.hitCount++;
+			this.totalTimeMetrics.hitTime += hitFinishedAt - startAt;
+			this.logger?.debug(this.name, "[getOrLoad] Cache hit.", "key =", key);
+		} else {
+			const setFinishAt = performance.now();
+			this.countMetrics.setCount++;
+			this.totalTimeMetrics.setTime += setFinishAt - loadFinishAt;
+		}
+		return data;
+	}
+	async set(key, value, options) {
+		const startAt = performance.now();
+		await this.cache.set(key, value, options);
+		const time = performance.now() - startAt;
+		this.countMetrics.setCount++;
+		this.totalTimeMetrics.setTime += time;
+		this.logger?.debug(this.name, "[set] Cache set.", "key =", key, "timeMS =", time);
+	}
+	async delete(key) {
+		const startAt = performance.now();
+		await this.cache.delete(key);
+		const time = performance.now() - startAt;
+		this.countMetrics.deleteCount++;
+		this.totalTimeMetrics.deleteTime += time;
+		this.logger?.debug(this.name, "[delete] Cache delete.", "key =", key, "timeMS =", time);
+	}
+	async getMany(keys) {
+		const startAt = performance.now();
+		const data = await this.cache.getMany(keys);
+		const time = performance.now() - startAt;
+		const timePerKey = time / keys.length;
+		const miss = keys.filter((key) => data[key] === void 0 || data[key] === null).length;
+		const hits = keys.length - miss;
+		this.countMetrics.missCount += miss;
+		this.countMetrics.hitCount += hits;
+		this.totalTimeMetrics.missTime += miss * timePerKey;
+		this.totalTimeMetrics.hitTime += hits * timePerKey;
+		this.logger?.debug(this.name, "[getMany]", "hits =", hits, "misses = ", miss, "timeMS =", time);
+		return data;
+	}
+	async setMany(data, options) {
+		const startAt = performance.now();
+		await this.cache.setMany(data, options);
+		const time = performance.now() - startAt;
+		const sets = Object.keys(data).length;
+		this.countMetrics.setCount += sets;
+		this.totalTimeMetrics.setTime += time;
+		this.logger?.debug(this.name, "[setMany]", "sets =", sets, "timeMS =", time);
+	}
+	async deleteMany(keys) {
+		const startAt = performance.now();
+		await this.cache.deleteMany(keys);
+		const time = performance.now() - startAt;
+		this.countMetrics.deleteCount += keys.length;
+		this.totalTimeMetrics.deleteTime += time;
+		this.logger?.debug(this.name, "[deleteMany]", "deletes =", keys.length, "timeMS =", time);
+	}
+	getMetrics() {
+		const count = this.countMetrics;
+		const time = this.totalTimeMetrics;
+		return {
+			...count,
+			missTime: count.missCount === 0 ? 0 : time.missTime / count.missCount,
+			hitTime: count.hitCount === 0 ? 0 : time.hitTime / count.hitCount,
+			loadTime: count.loadCount === 0 ? 0 : time.loadTime / count.loadCount,
+			setTime: count.setCount === 0 ? 0 : time.setTime / count.setCount,
+			deleteTime: count.deleteCount === 0 ? 0 : time.deleteTime / count.deleteCount
+		};
+	}
+	resetMetrics() {
+		this.countMetrics = {
+			missCount: 0,
+			hitCount: 0,
+			loadCount: 0,
+			setCount: 0,
+			deleteCount: 0
+		};
+		this.totalTimeMetrics = {
+			missTime: 0,
+			hitTime: 0,
+			loadTime: 0,
+			setTime: 0,
+			deleteTime: 0
+		};
+		this.logger?.debug(this.name, "[resetMetrics]");
+	}
+};
+
+//#endregion
+exports.AsyncLazyCache = AsyncLazyCache;
+exports.BaseCache = BaseCache;
+exports.CoalescingCache = CoalescingCache;
+exports.IORedisCache = IORedisCache;
+exports.JitteringCache = JitteringCache;
+exports.KeyTransformingCache = KeyTransformingCache;
+exports.KeyvCache = KeyvCache;
+exports.LocalLRUCache = LocalLRUCache;
+exports.LocalMapCache = LocalMapCache;
+exports.LocalTTLCache = LocalTTLCache;
+exports.MemJSCache = MemJSCache;
+exports.MemcacheCache = MemcacheCache;
+exports.MetricsCollectingCache = MetricsCollectingCache;
+exports.NoOpCache = NoOpCache;
+exports.RedisCache = RedisCache;
+exports.SWRCache = SWRCache;
+exports.TieredCache = TieredCache;
+exports.ValkeyGlideCache = ValkeyGlideCache;
+exports.WorkersKVCache = WorkersKVCache;