cachimbo 0.0.2 → 0.0.4

package/README.md

@@ -18,6 +18,7 @@ Cachimbo is an advanced caching library that allows you to layer different strat
   - Least Recently Used (LRU) eviction
   - Time-based (TTL) eviction
   - FIFO eviction
+  - Weak References (garbage collectable cached items)
 - Supports intermediary cache strategies
   - Request coalescing (deduplication)
   - Multi-layer caching (tiered cache)

package/dist/index.cjs

@@ -40,6 +40,76 @@ var BaseCache = class {
 	}
 };
 
+//#endregion
+//#region src/base/local.ts
+var BaseLocalCache = class extends BaseCache {
+	disposeListeners = [];
+	/**
+	* Reads cached resources by their keys. (synchronous version)
+	*/
+	_getMany(keys) {
+		return Object.fromEntries(keys.map((key) => [key, this._get(key)]));
+	}
+	/**
+	* Writes resources into cache. (synchronous version)
+	*/
+	_setMany(data, options) {
+		for (const [key, value] of Object.entries(data)) this._set(key, value, options);
+	}
+	/**
+	* Deletes many cached resources by their keys. (synchronous version)
+	*/
+	_deleteMany(keys) {
+		for (const key of keys) this._delete(key);
+	}
+	/**
+	* Adds a listener that will be called when a cached item is disposed.
+	*
+	* @param listener The listener function to add.
+	*/
+	_addDisposeListener(listener) {
+		this.disposeListeners.push(listener);
+	}
+	/**
+	* Gets access to the internal synchronous methods.
+	* @experimental
+	*/
+	get internal() {
+		return this;
+	}
+	/** @sealed **/
+	get(key) {
+		return Promise.resolve(this._get(key));
+	}
+	/** @sealed **/
+	set(key, value, options) {
+		this._set(key, value, options);
+		return Promise.resolve();
+	}
+	/** @sealed **/
+	delete(key) {
+		this._delete(key);
+		return Promise.resolve();
+	}
+	/** @sealed **/
+	getMany(keys) {
+		return Promise.resolve(this._getMany(keys));
+	}
+	/** @sealed **/
+	setMany(data, options) {
+		this._setMany(data, options);
+		return Promise.resolve();
+	}
+	/** @sealed **/
+	deleteMany(keys) {
+		this._deleteMany(keys);
+		return Promise.resolve();
+	}
+	onDispose(key, value, reason) {
+		for (const listener of this.disposeListeners) listener(key, value, reason);
+	}
+};
+
 //#endregion
 //#region src/local/lru/index.ts
 /**
@@ -49,7 +119,7 @@ var BaseCache = class {
 *
 * Once the limit of items is reached, the least recently used items will be purged.
 */
-var LocalLRUCache = class extends BaseCache {
+var LocalLRUCache = class extends BaseLocalCache {
 	cache;
 	shouldUseFetch;
 	constructor(options = {}) {
@@ -62,16 +132,29 @@ var LocalLRUCache = class extends BaseCache {
 				ttl: options.ttl ? options.ttl * 1e3 : void 0,
 				max: options.max || 1e4,
 				ttlAutopurge: false,
-				fetchMethod: (_key, _staleValue, options$1) => options$1.context()
+				fetchMethod: (_key, _staleValue, options$1) => options$1.context(),
+				disposeAfter: (value, key, reason) => this.onDispose(key, value, reason)
 			});
 			this.shouldUseFetch = true;
 		}
 	}
-	async get(key) {
+	/** @internal */
+	_get(key) {
 		this.logger?.debug(this.name, "[get]", "key =", key);
 		const data = this.cache.get(key);
 		return data === void 0 ? null : data;
 	}
+	/** @internal */
+	_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 });
+	}
+	/** @internal */
+	_delete(key) {
+		this.logger?.debug(this.name, "[delete]", "key =", key);
+		this.cache.delete(key);
+	}
 	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);
@@ -81,15 +164,6 @@ var LocalLRUCache = class extends BaseCache {
 			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
@@ -99,27 +173,31 @@ var LocalLRUCache = class extends BaseCache {
 *
 * Once the limit of items is reached, the soonest expiring items will be purged.
 */
-var LocalTTLCache = class extends BaseCache {
+var LocalTTLCache = class extends BaseLocalCache {
 	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
+			ttl: options.ttl ? options.ttl * 1e3 : void 0,
+			dispose: (value, key, reason) => this.onDispose(key, value, reason)
 		});
 	}
-	async get(key) {
+	/** @internal */
+	_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) {
+	/** @internal */
+	_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) {
+	/** @internal */
+	_delete(key) {
 		this.logger?.debug(this.name, "[delete]", "key =", key);
 		this.cache.delete(key);
 	}
@@ -135,7 +213,7 @@ var LocalTTLCache = class extends BaseCache {
 * It implements a simple FIFO eviction policy:
 * Once the limit of items is reached, the first inserted keys will be purged.
 */
-var LocalMapCache = class extends BaseCache {
+var LocalMapCache = class extends BaseLocalCache {
 	cache;
 	max;
 	constructor(options = {}) {
@@ -143,47 +221,177 @@ var LocalMapCache = class extends BaseCache {
 		this.cache = options.cache ?? /* @__PURE__ */ new Map();
 		this.max = options.max ?? Infinity;
 	}
-	async get(key) {
+	/** @internal */
+	_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) {
+	/** @internal */
+	_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);
+		const previousValue = this.cache.get(key);
+		if (this.cache.size >= this.max && previousValue === void 0) this.evict(1);
 		this.cache.set(key, value);
+		this.onDispose(key, previousValue, "set");
 	}
-	async delete(key) {
+	/** @internal */
+	_delete(key) {
 		this.logger?.debug(this.name, "[delete]", "key =", key);
+		const previousValue = this.cache.get(key);
 		this.cache.delete(key);
+		this.onDispose(key, previousValue, "delete");
 	}
 	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);
+		for (const [key, value] of entries) {
+			const previousValue = this.cache.get(key);
+			this.cache.set(key, value);
+			this.onDispose(key, previousValue, "set");
+		}
 	}
 	clear() {
 		this.logger?.debug(this.name, "[clear]");
+		for (const key of this.cache.keys()) this.onDispose(key, this.cache.get(key), "delete");
 		this.cache.clear();
 	}
+	onDispose(key, value, reason) {
+		if (value !== void 0) super.onDispose(key, value, reason);
+	}
 	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);
+			const previousValue = this.cache.get(key.value);
 			this.cache.delete(key.value);
+			this.onDispose(key.value, previousValue, "evict");
 		}
 	}
 };
 
+//#endregion
+//#region src/local/weak/index.ts
+/**
+* A cache layer that stores objects as weak references.
+*
+* When an object is garbage collected, its entry is automatically removed from the underlying cache.
+*
+* This implementation requires support for both `WeakRef` and `FinalizationRegistry`.
+*
+* @see https://caniuse.com/mdn-javascript_builtins_finalizationregistry
+* @see https://caniuse.com/mdn-javascript_builtins_weakref
+*/
+var WeakCache = class extends BaseLocalCache {
+	cache;
+	cacheInternal;
+	registry;
+	constructor(options) {
+		super(options);
+		this.cache = options.cache;
+		this.cacheInternal = options.cache.internal;
+		this.cacheInternal._addDisposeListener(this.onCacheDispose);
+		this.registry = new FinalizationRegistry(this.onGarbageCollect);
+	}
+	onGarbageCollect = (key) => this.cacheInternal._delete(key);
+	onCacheDispose = (key, value, reason) => {
+		this.unregister(value);
+		this.onDispose(key, this.unwrap(value), reason);
+	};
+	/** @internal */
+	_get(key) {
+		return this.unwrap(this.cacheInternal._get(key));
+	}
+	/** @internal */
+	_set(key, value, options) {
+		this.cacheInternal._set(key, this.wrapAndRegister(key, value), options);
+	}
+	/** @internal */
+	_delete(key) {
+		this.unregisterByKey(key);
+		this.cacheInternal._delete(key);
+	}
+	/** @internal */
+	_getMany(keys) {
+		const data = this.cacheInternal._getMany(keys);
+		for (const key of keys) data[key] = this.unwrap(data[key]);
+		return data;
+	}
+	/** @internal */
+	_setMany(data, options) {
+		Object.keys(data).forEach((key) => this.unregisterByKey(key));
+		const wrappedData = {};
+		for (const [key, value] of Object.entries(data)) wrappedData[key] = this.wrapAndRegister(key, value);
+		this.cacheInternal._setMany(wrappedData, options);
+	}
+	/** @internal */
+	_deleteMany(keys) {
+		keys.forEach((key) => this.unregisterByKey(key));
+		this.cacheInternal._deleteMany(keys);
+	}
+	async getOrLoad(key, load, options) {
+		const wrappedLoad = async () => this.wrapAndRegister(key, await load());
+		return this.unwrap(await this.cache.getOrLoad(key, wrappedLoad, options));
+	}
+	/**
+	* Wraps the value in a WeakRef and registers it in the FinalizationRegistry if it's an object.
+	*
+	* @param key The key to reference the value in the FinalizationRegistry
+	* @param value The value to wrap
+	* @returns The wrapped value
+	*/
+	wrapAndRegister(key, value) {
+		this.unregisterByKey(key);
+		if (value !== null && typeof value === "object") {
+			this.registry.register(value, key);
+			return {
+				v: new WeakRef(value),
+				w: true
+			};
+		}
+		return {
+			v: value,
+			w: false
+		};
+	}
+	/**
+	* Unwraps the value from a WeakRef if it's an object.
+	*
+	* @param data The data to unwrap
+	* @returns The unwrapped value
+	*/
+	unwrap(data) {
+		if (data === null) return null;
+		if (data.w) return data.v.deref() ?? null;
+		return data.v;
+	}
+	/**
+	* Unregisters the value from the FinalizationRegistry if it's an object.
+	*
+	* @param value The value to unregister
+	*/
+	unregister(value) {
+		if (value && value.w) this.registry.unregister(value.v);
+	}
+	/**
+	* Unregisters the value associated with the given key from the FinalizationRegistry.
+	*
+	* @param key The key
+	*/
+	unregisterByKey(key) {
+		this.unregister(this.cacheInternal._get(key));
+	}
+};
+
 //#endregion
 //#region src/local/noop/index.ts
 /**
 * A cache implementation that does nothing.
-* It's useful for disabling cache.
+* It's useful for disabling cache and unit testing.
 *
 * @example
 * ```ts
@@ -215,12 +423,14 @@ var NoOpCache = class {
 var IORedisCache = class extends BaseCache {
 	client;
 	defaultTTL;
+	isUNLINKSupported;
 	isMSETEXSupported;
 	constructor(options) {
 		super(options);
 		this.client = options.client;
 		this.defaultTTL = options.defaultTTL;
-		this.isMSETEXSupported = options.isMSETEXSupported;
+		this.isUNLINKSupported = options.isUNLINKSupported ?? true;
+		this.isMSETEXSupported = options.isMSETEXSupported ?? false;
 	}
 	async get(key) {
 		this.logger?.debug(this.name, "[get] Running \"GET\" command...", "key =", key);
@@ -235,8 +445,13 @@ var IORedisCache = class extends BaseCache {
 		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);
+		if (this.isUNLINKSupported) {
+			this.logger?.debug(this.name, "[delete] Running \"UNLINK\" command...", "key =", key);
+			await this.client.unlink(key);
+		} else {
+			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);
@@ -257,8 +472,13 @@ var IORedisCache = class extends BaseCache {
 		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);
+		if (this.isUNLINKSupported) {
+			this.logger?.debug(this.name, "[deleteMany] Running \"UNLINK\" command...", "keys =", keys);
+			await this.client.unlink(keys);
+		} else {
+			this.logger?.debug(this.name, "[deleteMany] Running \"DEL\" command...", "keys =", keys);
+			await this.client.del(keys);
+		}
 	}
 };
 
@@ -270,12 +490,14 @@ var IORedisCache = class extends BaseCache {
 var RedisCache = class extends BaseCache {
 	client;
 	defaultTTL;
+	isUNLINKSupported;
 	isMSETEXSupported;
 	constructor(options) {
 		super(options);
 		this.client = options.client;
 		this.defaultTTL = options.defaultTTL;
-		this.isMSETEXSupported = options.isMSETEXSupported;
+		this.isUNLINKSupported = options.isUNLINKSupported ?? true;
+		this.isMSETEXSupported = options.isMSETEXSupported ?? false;
 	}
 	async get(key) {
 		this.logger?.debug(this.name, "[get] Running \"GET\" command...", "key =", key);
@@ -291,8 +513,13 @@ var RedisCache = class extends BaseCache {
 		} : void 0 });
 	}
 	async delete(key) {
-		this.logger?.debug(this.name, "[delete] Running \"DEL\" command...", "key =", key);
-		await this.client.del(key);
+		if (this.isUNLINKSupported) {
+			this.logger?.debug(this.name, "[delete] Running \"UNLINK\" command...", "key =", key);
+			await this.client.unlink(key);
+		} else {
+			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);
@@ -316,8 +543,13 @@ var RedisCache = class extends BaseCache {
 		} : void 0 });
 	}
 	async deleteMany(keys) {
-		this.logger?.debug(this.name, "[deleteMany] Running \"DEL\" command...", "keys =", keys);
-		await this.client.del(keys);
+		if (this.isUNLINKSupported) {
+			this.logger?.debug(this.name, "[deleteMany] Running \"UNLINK\" command...", "keys =", keys);
+			await this.client.unlink(keys);
+		} else {
+			this.logger?.debug(this.name, "[deleteMany] Running \"DEL\" command...", "keys =", keys);
+			await this.client.del(keys);
+		}
 	}
 };
 
@@ -348,8 +580,8 @@ var ValkeyGlideCache = class extends BaseCache {
 		} : void 0 });
 	}
 	async delete(key) {
-		this.logger?.debug(this.name, "[delete] Running \"DEL\" command...", "key =", key);
-		await this.client.del([key]);
+		this.logger?.debug(this.name, "[delete] Running \"UNLINK\" command...", "key =", key);
+		await this.client.unlink([key]);
 	}
 	async getMany(keys) {
 		this.logger?.debug(this.name, "[getMany] Running \"MGET\" command...", "keys =", keys);
@@ -362,8 +594,8 @@ var ValkeyGlideCache = class extends BaseCache {
 		return data;
 	}
 	async deleteMany(keys) {
-		this.logger?.debug(this.name, "[deleteMany] Running \"DEL\" command...", "keys =", keys);
-		await this.client.del(keys);
+		this.logger?.debug(this.name, "[deleteMany] Running \"UNLINK\" command...", "keys =", keys);
+		await this.client.unlink(keys);
 	}
 };
 
@@ -458,7 +690,10 @@ var WorkersKVCache = class extends BaseCache {
 		return this.kv.delete(key);
 	}
 	async getMany(keys) {
-		const data = await this.kv.get(keys, { type: "json" });
+		const data = await this.kv.get(keys, {
+			type: "json",
+			cacheTtl: this.edgeCacheTTL
+		});
 		return Object.fromEntries(data);
 	}
 };
@@ -1107,6 +1342,7 @@ var MetricsCollectingCache = class {
 //#endregion
 exports.AsyncLazyCache = AsyncLazyCache;
 exports.BaseCache = BaseCache;
+exports.BaseLocalCache = BaseLocalCache;
 exports.CoalescingCache = CoalescingCache;
 exports.IORedisCache = IORedisCache;
 exports.JitteringCache = JitteringCache;
@@ -1123,4 +1359,5 @@ exports.RedisCache = RedisCache;
 exports.SWRCache = SWRCache;
 exports.TieredCache = TieredCache;
 exports.ValkeyGlideCache = ValkeyGlideCache;
+exports.WeakCache = WeakCache;
 exports.WorkersKVCache = WorkersKVCache;