@warlock.js/cache 5.16.0 → 5.17.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `@warlock.js/cache` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.17.0 (Unreleased)
+
+### Changed
+
+- Cache misses and expiries log at `info` instead of `warn`. A cache miss or expiry is normal behaviour, not a warning.
+
+### Fixed
+
+- `cache.tags([...]).invalidate()` now deletes the tagged entries when a `globalPrefix` is configured, whether static (`"store"`) or a function. Before, the tag index stored each key with the prefix already applied, and invalidation passed that key back through `remove()`, which applied the prefix a second time. So it dropped the tag index but deleted none of the tagged entries, and reads stayed stale until TTL. Every scaffolded app sets a `globalPrefix`. The tag index now stores the un-prefixed key in all of these paths: `tags().set()`, inline `set(key, value, { tags })`, `tags().remove()`, the scoped `cache.namespace(...).tags(...)` handle (including `setNX`), and the `similar()` tag filter. `remove()` applies the prefix exactly once, on every driver. With a function prefix, invalidation uses the prefix that is current when it runs, which is the same prefix the tag index itself is read under. The two therefore agree as long as the prefix is stable for a given app or tenant.
+- `MemoryCacheDriver.similar()` returned no results whenever a `globalPrefix` was set, because it read each stored, already-prefixed key back through `get()`, which prefixed it again. It now reads entries by their stored key.
+- **Upgrade note:** entries tagged before this upgrade are indexed under the old, already-prefixed form, so invalidation still can't reach them. Their tag index is dropped on the first `invalidate()`, which leaves those entries orphaned. They expire by their TTL, or `flush()` clears them right away.
+
 ## 5.15.0 - 2026-09-18
 
 ### Fixed

package/cjs/index.cjs

@@ -627,8 +627,7 @@ var TaggedScopedCache = class {
 		const allTags = mergeTagSets(this.scope.defaults.tags, this.handleTags);
 		if (!allTags || allTags.length === 0) return true;
 		const scopedKey = this.buildScopedKey(key);
-		const parsedKey = this.scope.source.parseKey(scopedKey);
-		await this.scope.source.tags(allTags).storeTagRelationship(parsedKey);
+		await this.scope.source.tags(allTags).storeTagRelationship(scopedKey);
 		return true;
 	}
 	/**
@@ -1662,20 +1661,36 @@ var TaggedCache = class {
 	* Public alias of the tag-index writer. Called by `BaseCacheDriver.applyTags`
 	* when tags are passed inline through `CacheSetOptions.tags`.
 	*
+	* Takes the caller's key, never the driver-parsed one — see {@link indexedKey}.
+	*
 	* @internal — public for cross-class use within this package; not part of the
 	* stable consumer API.
 	*/
-	async storeTagRelationship(parsedKey) {
+	async storeTagRelationship(key) {
+		const indexedKey = this.indexedKey(key);
 		for (const tag of this.cacheTags) {
 			const tagKey = this.tagKey(tag);
 			const keys = await this.driver.get(tagKey) || [];
-			if (!keys.includes(parsedKey)) {
-				keys.push(parsedKey);
+			if (!keys.includes(indexedKey)) {
+				keys.push(indexedKey);
 				await this.driver.set(tagKey, keys, Infinity);
 			}
 		}
 	}
 	/**
+	* The form a key takes inside a tag index: normalized but un-prefixed.
+	*
+	* The index is read back and deleted through `driver.remove(key)`, which
+	* applies `globalPrefix` itself — so the index must hold the key *before*
+	* the prefix, or invalidation would prefix it twice and delete nothing.
+	* With a function prefix, the current prefix is re-applied at invalidation
+	* time; the tag index key is resolved under that same prefix, so the two
+	* agree as long as the prefix is stable for a given request/tenant.
+	*/
+	indexedKey(key) {
+		return parseCacheKey(key);
+	}
+	/**
 	* Get all keys associated with tags
 	*/
 	async getTaggedKeys() {
@@ -1691,9 +1706,8 @@ var TaggedCache = class {
 	* {@inheritdoc}
 	*/
 	async set(key, value, ttlOrOptions) {
-		const parsedKey = this.driver.parseKey(key);
 		await this.driver.set(key, value, ttlOrOptions);
-		await this.storeTaggedKey(parsedKey);
+		await this.storeTaggedKey(key);
 		return value;
 	}
 	/**
@@ -1706,11 +1720,11 @@ var TaggedCache = class {
 	* {@inheritdoc}
 	*/
 	async remove(key) {
-		const parsedKey = this.driver.parseKey(key);
+		const indexedKey = this.indexedKey(key);
 		await this.driver.remove(key);
 		for (const tag of this.cacheTags) {
 			const tagKey = this.tagKey(tag);
-			const updatedKeys = (await this.driver.get(tagKey) || []).filter((k) => k !== parsedKey);
+			const updatedKeys = (await this.driver.get(tagKey) || []).filter((k) => k !== indexedKey);
 			await this.driver.set(tagKey, updatedKeys, Infinity);
 		}
 	}
@@ -1905,6 +1919,8 @@ var BaseCacheDriver = class {
 	* Used by `similar()` to narrow the candidate pool before similarity ranking.
 	*
 	* Returns `null` when no tags are passed (callers should treat that as "no filter").
+	* Keys come back parsed (prefixed) — the index stores them un-prefixed, but
+	* callers match them against their own parsed storage keys.
 	*/
 	async getKeysForTags(tags) {
 		if (!tags || tags.length === 0) return null;
@@ -1912,17 +1928,20 @@ var BaseCacheDriver = class {
 		for (const tag of tags) {
 			const tagKey = `cache:tags:${tag}`;
 			const keys = await this.get(tagKey) || [];
-			for (const k of keys) allKeys.add(k);
+			for (const k of keys) allKeys.add(this.parseKey(k));
 		}
 		return allKeys;
 	}
 	/**
 	* Apply tag relationships after a successful write. Called by drivers once
 	* the value is in storage.
+	*
+	* Pass the caller's key, not the parsed one: the tag index stores keys
+	* un-prefixed so `invalidate()` can delete them through `remove(key)`.
 	*/
-	async applyTags(parsedKey, tags) {
+	async applyTags(key, tags) {
 		if (tags.length === 0) return;
-		await this.tags(tags).storeTagRelationship(parsedKey);
+		await this.tags(tags).storeTagRelationship(key);
 	}
 	/**
 	* {@inheritdoc}
@@ -2113,7 +2132,7 @@ var BaseCacheDriver = class {
 		if (!this.shouldLog) return;
 		if (typeof key === "string") key = key.replace(/\//g, ".");
 		if (operation === "connectionFailed") _warlock_js_logger.log.fatal(`cache.${this.name}`, operation, key);
-		if (operation == "notFound" || operation == "expired") return _warlock_js_logger.log.warn("cache." + this.name, operation, (key ? key + " " : "") + messages[operation]);
+		if (operation == "notFound" || operation == "expired") return _warlock_js_logger.log.info("cache." + this.name, operation, (key ? key + " " : "") + messages[operation]);
 		if (operation.endsWith("ed")) return _warlock_js_logger.log.success("cache." + this.name, operation, (key ? key + " " : "") + messages[operation]);
 		_warlock_js_logger.log.info("cache." + this.name, operation, (key ? key + " " : "") + messages[operation]);
 	}
@@ -2422,7 +2441,7 @@ var FileCacheDriver = class extends BaseCacheDriver {
 		const fileDirectory = this.keyDirectory(parsedKey);
 		await (0, _warlock_js_fs.ensureDirectoryAsync)(fileDirectory);
 		await (0, _warlock_js_fs.putJsonFileAsync)(path.default.resolve(fileDirectory, this.fileName), data);
-		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		if (tags && tags.length > 0) await this.applyTags(key, tags);
 		this.log("cached", parsedKey);
 		await this.emit("set", {
 			key: parsedKey,
@@ -2652,7 +2671,7 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 			this.addNode(newNode);
 			if (this.cache.size > this.capacity) this.removeTail();
 		}
-		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		if (tags && tags.length > 0) await this.applyTags(key, tags);
 		this.log("cached", parsedKey);
 		await this.emit("set", {
 			key: parsedKey,
@@ -2906,7 +2925,7 @@ var MemoryCacheDriver = class extends BaseCacheDriver {
 		(0, _mongez_reinforcements.set)(this.data, parsedKey, data);
 		this.trackAccess(parsedKey);
 		if (!exists && this.options.maxSize) await this.enforceMaxSize();
-		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		if (tags && tags.length > 0) await this.applyTags(key, tags);
 		if (vector) this.vectorIndex.set(parsedKey, vector.slice());
 		this.log("cached", parsedKey);
 		await this.emit("set", {
@@ -3047,8 +3066,14 @@ var MemoryCacheDriver = class extends BaseCacheDriver {
 		const hits = [];
 		for (const [parsedKey, stored] of this.vectorIndex) {
 			if (tagFilter && !tagFilter.has(parsedKey)) continue;
-			const value = await this.get(parsedKey);
-			if (value === null) continue;
+			const entry = (0, _mongez_reinforcements.get)(this.data, parsedKey);
+			if (!entry) continue;
+			if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) continue;
+			let value = entry.data;
+			if (value !== null && value !== void 0) {
+				const type = typeof value;
+				if (type !== "string" && type !== "number" && type !== "boolean") value = structuredClone(value);
+			}
 			const score = cosineSimilarity(vector, stored);
 			if (options.threshold !== void 0 && score < options.threshold) continue;
 			hits.push({
@@ -3200,7 +3225,7 @@ var MockCacheDriver = class extends BaseCacheDriver {
 		};
 		const data = this.prepareDataForStorage(value, ttl, staleAt);
 		this.storage.set(parsedKey, data);
-		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		if (tags && tags.length > 0) await this.applyTags(key, tags);
 		this.log("cached", parsedKey);
 		await this.emit("set", {
 			key: parsedKey,
@@ -3625,7 +3650,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
 				wasSet: false,
 				existing: await this.get(key)
 			};
-			if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+			if (tags && tags.length > 0) await this.applyTags(key, tags);
 			this.log("cached", parsedKey);
 			await this.emit("set", {
 				key: parsedKey,
@@ -3646,7 +3671,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
 				wasSet: false,
 				existing: null
 			};
-			if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+			if (tags && tags.length > 0) await this.applyTags(key, tags);
 			this.log("cached", parsedKey);
 			await this.emit("set", {
 				key: parsedKey,
@@ -3662,7 +3687,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
        VALUES (${valList})
        ON CONFLICT (key) DO UPDATE
          SET ${setClause}`, params);
-		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		if (tags && tags.length > 0) await this.applyTags(key, tags);
 		this.log("cached", parsedKey);
 		await this.emit("set", {
 			key: parsedKey,
@@ -3932,7 +3957,7 @@ var RedisCacheDriver = class extends BaseCacheDriver {
 			wasSet: false,
 			existing: onConflict === "create" ? await this.get(key) : null
 		};
-		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		if (tags && tags.length > 0) await this.applyTags(key, tags);
 		if (staleAt !== void 0) {
 			const sidecarOptions = {};
 			if (hasExpiry) sidecarOptions.EX = ttl;