@c9up/echo 0.1.3

package/src/drivers/MemoryDriver.ts

@@ -0,0 +1,151 @@
+/**
+ * Memory cache driver — in-process Map with TTL support.
+ * Suitable for development and single-process deployments.
+ */
+
+import type { CacheDriver } from "../CacheManager.js";
+
+interface CacheEntry {
+	value: unknown;
+	expiresAt: number;
+	tags: string[];
+}
+
+export class MemoryDriver implements CacheDriver {
+	#store: Map<string, CacheEntry> = new Map();
+	#tagIndex: Map<string, Set<string>> = new Map();
+	#sweepInterval: ReturnType<typeof setInterval>;
+
+	constructor(sweepIntervalMs = 60_000) {
+		this.#sweepInterval = setInterval(() => {
+			const now = Date.now();
+			for (const [key, entry] of this.#store) {
+				if (entry.expiresAt > 0 && entry.expiresAt < now) {
+					this.#store.delete(key);
+				}
+			}
+		}, sweepIntervalMs);
+		if (
+			typeof this.#sweepInterval === "object" &&
+			"unref" in this.#sweepInterval
+		) {
+			(this.#sweepInterval as { unref(): void }).unref();
+		}
+	}
+
+	destroy(): void {
+		clearInterval(this.#sweepInterval);
+	}
+
+	async get<T = unknown>(key: string): Promise<T | null> {
+		const entry = this.#store.get(key);
+		if (!entry) return null;
+		if (entry.expiresAt > 0 && entry.expiresAt < Date.now()) {
+			this.#store.delete(key);
+			return null;
+		}
+		return entry.value as T;
+	}
+
+	async set(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
+		if (value === null || value === undefined) {
+			throw new TypeError(
+				"Echo: caching null/undefined values is not supported",
+			);
+		}
+		const expiresAt =
+			ttlSeconds != null && ttlSeconds > 0 ? Date.now() + ttlSeconds * 1000 : 0;
+		this.#store.set(key, { value, expiresAt, tags: [] });
+	}
+
+	async delete(key: string): Promise<boolean> {
+		const entry = this.#store.get(key);
+		if (entry) {
+			for (const tag of entry.tags) {
+				this.#tagIndex.get(tag)?.delete(key);
+			}
+		}
+		return this.#store.delete(key);
+	}
+
+	async flush(): Promise<void> {
+		this.#store.clear();
+		this.#tagIndex.clear();
+	}
+
+	async has(key: string): Promise<boolean> {
+		const val = await this.get(key);
+		return val !== null;
+	}
+
+	/** Set with tags for group invalidation. */
+	async setWithTags(
+		key: string,
+		value: unknown,
+		tags: string[],
+		ttlSeconds?: number,
+	): Promise<void> {
+		// Audit 2026-05-22 F4: align with `set()` — both paths now treat any
+		// `ttlSeconds <= 0` (and undefined) as "no expiration". Previously
+		// `setWithTags` used a truthy check (`ttlSeconds ?`), which let a
+		// negative value through and produced `Date.now() + (-N * 1000)` —
+		// an already-past timestamp — so the entry was born already-expired.
+		// `set()` correctly returned the immortal-entry branch on the same
+		// input. The divergence made cache semantics depend on whether the
+		// caller used tags or not, which is the worst kind of "very hard to
+		// diagnose in prod" bug.
+		const expiresAt =
+			ttlSeconds != null && ttlSeconds > 0 ? Date.now() + ttlSeconds * 1000 : 0;
+		// Audit 2026-05-22 F3 (overwrite leg): if `key` already exists with
+		// a different tag set, the old #tagIndex entries become dangling
+		// refs to the (now overwritten) key. Clean them up before re-tagging
+		// so subsequent flushTags doesn't iterate stale references.
+		const prev = this.#store.get(key);
+		if (prev !== undefined) {
+			for (const t of prev.tags) this.#tagIndex.get(t)?.delete(key);
+		}
+		this.#store.set(key, { value, expiresAt, tags });
+		for (const tag of tags) {
+			let set = this.#tagIndex.get(tag);
+			if (!set) {
+				set = new Set();
+				this.#tagIndex.set(tag, set);
+			}
+			set.add(key);
+		}
+	}
+
+	/** Flush all entries tagged with any of the given tags. */
+	async flushTags(tags: string[]): Promise<void> {
+		// Audit 2026-05-22 F3: when a key is multi-tagged (e.g. `[news, fr]`)
+		// and we flush by `news`, the old code deleted the key from #store
+		// and dropped the `news` Set, but `fr`'s Set kept a dangling
+		// reference. A later flushTags(`fr`) would iterate over the
+		// stale entry, attempt `#store.delete(key)` (no-op), and the entry
+		// would silently linger in #tagIndex forever. Worse — if a new
+		// entry was later written under the same key with different tags,
+		// flushTags(`fr`) would WRONGLY purge it because of the residue.
+		// Collect keys first, then scrub each one from EVERY tag set it
+		// belonged to (including the tags we're not flushing this round).
+		const toDelete = new Set<string>();
+		for (const tag of tags) {
+			const keys = this.#tagIndex.get(tag);
+			if (keys) {
+				for (const key of keys) toDelete.add(key);
+			}
+		}
+		for (const key of toDelete) {
+			const entry = this.#store.get(key);
+			if (entry) {
+				for (const t of entry.tags) {
+					this.#tagIndex.get(t)?.delete(key);
+				}
+			}
+			this.#store.delete(key);
+		}
+		// Now drop the flushed tag sets themselves (any other keys still
+		// referenced by them have been processed in the toDelete loop and
+		// already removed via the inner scrub).
+		for (const tag of tags) this.#tagIndex.delete(tag);
+	}
+}

package/src/drivers/RedisDriver.ts

@@ -0,0 +1,211 @@
+/**
+ * Redis cache driver — production-grade cache with TTL and tags.
+ *
+ * Requires a Redis client instance implementing the minimal interface below.
+ * Compatible with ioredis and redis (node-redis) clients.
+ *
+ * @implements MISS-10
+ */
+
+import type { CacheDriver } from "../CacheManager.js";
+
+/** Minimal Redis client interface — compatible with ioredis and node-redis. */
+export interface RedisClient {
+	get(key: string): Promise<string | null>;
+	set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+	del(key: string | string[]): Promise<number>;
+	exists(key: string): Promise<number>;
+	keys(pattern: string): Promise<string[]>;
+	sadd(key: string, ...members: string[]): Promise<number>;
+	srem(key: string, ...members: string[]): Promise<number>;
+	smembers(key: string): Promise<string[]>;
+	expire(key: string, seconds: number): Promise<number>;
+	ttl(key: string): Promise<number>;
+	scan?(
+		cursor: string,
+		matchOption: "MATCH",
+		pattern: string,
+		countOption: "COUNT",
+		count: number,
+	): Promise<[string, string[]]>;
+}
+
+export class RedisDriver implements CacheDriver {
+	#client: RedisClient;
+	#prefix: string;
+
+	constructor(client: RedisClient, prefix = "cache:") {
+		this.#client = client;
+		this.#prefix = prefix;
+	}
+
+	#key(k: string): string {
+		return `${this.#prefix}${k}`;
+	}
+
+	/**
+	 * Reverse-index for per-key tag membership. Lets `setWithTags()` clean
+	 * stale memberships when a key is retagged, and `delete()` drop the key
+	 * from every tag-set it belongs to. Without this, a re-tag like
+	 * `setWithTags('article:42', v, ['homepage'])` (was `['news']`) leaves
+	 * `tag:news` pointing at `article:42`, and a later `flushTags(['news'])`
+	 * silently deletes the value.
+	 */
+	#metaKey(k: string): string {
+		return `${this.#prefix}meta:tags:${k}`;
+	}
+
+	async delete(key: string): Promise<boolean> {
+		const fullKey = this.#key(key);
+		const metaKey = this.#metaKey(key);
+		const tags = await this.#client.smembers(metaKey);
+		for (const tag of tags) {
+			const tagKey = `${this.#prefix}tag:${tag}`;
+			await this.#client.srem(tagKey, fullKey);
+		}
+		if (tags.length > 0) {
+			await this.#client.del(metaKey);
+		}
+		const count = await this.#client.del(fullKey);
+		return count > 0;
+	}
+
+	async get<T = unknown>(key: string): Promise<T | null> {
+		const raw = await this.#client.get(this.#key(key));
+		if (raw === null) return null;
+		return JSON.parse(raw) as T;
+	}
+
+	async set(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
+		const serialized = JSON.stringify(value);
+		if (ttlSeconds && ttlSeconds > 0) {
+			await this.#client.set(this.#key(key), serialized, "EX", ttlSeconds);
+		} else {
+			await this.#client.set(this.#key(key), serialized);
+		}
+	}
+
+	async flush(): Promise<void> {
+		const scan = this.#client.scan;
+		if (typeof scan === "function") {
+			let cursor = "0";
+			do {
+				const [nextCursor, keys] = await scan(
+					cursor,
+					"MATCH",
+					`${this.#prefix}*`,
+					"COUNT",
+					100,
+				);
+				cursor = nextCursor;
+				if (keys.length > 0) {
+					await this.#client.del(keys);
+				}
+			} while (cursor !== "0");
+		} else {
+			throw new Error(
+				"Echo: RedisDriver.flush() requires a client with scan() support. KEYS is not safe for production use.",
+			);
+		}
+	}
+
+	async has(key: string): Promise<boolean> {
+		const exists = await this.#client.exists(this.#key(key));
+		return exists > 0;
+	}
+
+	/**
+	 * Set a value with tag memberships for group invalidation.
+	 *
+	 * Re-tagging an existing key (e.g. `['news']` → `['homepage']`) cleans
+	 * the stale memberships via the per-key reverse-index — without this,
+	 * a later `flushTags(['news'])` would silently wipe the still-current
+	 * value because the abandoned `tag:news` set kept pointing at it.
+	 */
+	async setWithTags(
+		key: string,
+		value: unknown,
+		tags: string[],
+		ttlSeconds?: number,
+	): Promise<void> {
+		await this.set(key, value, ttlSeconds);
+		const fullKey = this.#key(key);
+		const metaKey = this.#metaKey(key);
+		const oldTags = await this.#client.smembers(metaKey);
+		const newTagSet = new Set(tags);
+		const oldTagSet = new Set(oldTags);
+		const removedTags = oldTags.filter((t) => !newTagSet.has(t));
+		const addedTags = tags.filter((t) => !oldTagSet.has(t));
+
+		// Drop the key from tag-sets it no longer belongs to.
+		for (const tag of removedTags) {
+			const tagKey = `${this.#prefix}tag:${tag}`;
+			await this.#client.srem(tagKey, fullKey);
+		}
+
+		// Add to new tag-sets; re-touch TTLs on every declared tag so existing
+		// memberships extend correctly on re-set.
+		for (const tag of tags) {
+			const tagKey = `${this.#prefix}tag:${tag}`;
+			if (addedTags.includes(tag)) {
+				await this.#client.sadd(tagKey, fullKey);
+			}
+			if (ttlSeconds && ttlSeconds > 0) {
+				const currentTtl = await this.#client.ttl(tagKey);
+				if (currentTtl < 0 || ttlSeconds > currentTtl) {
+					await this.#client.expire(tagKey, ttlSeconds);
+				}
+			}
+		}
+
+		// Refresh the reverse-index to match the new tag set. Drop+re-add is
+		// simpler than diff-mutating the set and matches `tags` exactly even
+		// in the empty-array case.
+		if (oldTags.length > 0) {
+			await this.#client.del(metaKey);
+		}
+		if (tags.length > 0) {
+			await this.#client.sadd(metaKey, ...tags);
+			if (ttlSeconds && ttlSeconds > 0) {
+				await this.#client.expire(metaKey, ttlSeconds);
+			}
+		}
+	}
+
+	/**
+	 * Flush all entries tagged with any of the given tags. Cleans up the
+	 * per-key reverse-index AND cross-tag memberships so a multi-tag key
+	 * (e.g. `['news', 'homepage']`) flushed via `news` is also removed from
+	 * the `homepage` tag-set — otherwise the `homepage` set ends up with a
+	 * dangling reference to a now-deleted value.
+	 */
+	async flushTags(tags: string[]): Promise<void> {
+		for (const tag of tags) {
+			const tagKey = `${this.#prefix}tag:${tag}`;
+			const members = await this.#client.smembers(tagKey);
+			for (const fullKey of members) {
+				// Read every OTHER tag this key claims (via the reverse-index)
+				// and SREM the key from each. The reverse-index key derives
+				// from the unprefixed user key — recover it by stripping the
+				// prefix.
+				const userKey = fullKey.startsWith(this.#prefix)
+					? fullKey.slice(this.#prefix.length)
+					: fullKey;
+				const metaKey = this.#metaKey(userKey);
+				const allTags = await this.#client.smembers(metaKey);
+				for (const otherTag of allTags) {
+					if (otherTag === tag) continue;
+					const otherTagKey = `${this.#prefix}tag:${otherTag}`;
+					await this.#client.srem(otherTagKey, fullKey);
+				}
+				if (allTags.length > 0) {
+					await this.#client.del(metaKey);
+				}
+			}
+			if (members.length > 0) {
+				await this.#client.del(members);
+			}
+			await this.#client.del(tagKey);
+		}
+	}
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @c9up/echo — Cache layer for the Ream framework.
+ *
+ * Provides get/set/delete/flush/tags with pluggable drivers (Memory, Redis).
+ *
+ * @implements MISS-10
+ */
+
+export type { CacheConfig, CacheDriver } from "./CacheManager.js";
+export { CacheManager } from "./CacheManager.js";
+export { MemoryDriver } from "./drivers/MemoryDriver.js";
+export type { RedisClient } from "./drivers/RedisDriver.js";
+export { RedisDriver } from "./drivers/RedisDriver.js";

package/src/services/main.ts

@@ -0,0 +1,41 @@
+/**
+ * Default `CacheManager` singleton — mirror of Adonis's
+ * `import cache from '@adonisjs/cache/services/main'` shape.
+ *
+ * Populated by `EchoProvider.boot()` or by the app directly through
+ * `setCache(myManager)` when the cache wiring needs custom config.
+ *
+ *   import cache from '@c9up/echo/services/main'
+ *
+ *   await cache.set('user:42', user, 60)
+ *   const cached = await cache.get<User>('user:42')
+ */
+
+import type { CacheManager } from "../CacheManager.js";
+
+let instance: CacheManager | undefined;
+
+/** @internal Bind the singleton (called by EchoProvider or by the app). */
+export function setCache(value: CacheManager): void {
+	instance = value;
+}
+
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export function getCache(): CacheManager | undefined {
+	return instance;
+}
+
+const cache: CacheManager = new Proxy({} as CacheManager, {
+	get(_target, prop) {
+		if (!instance) {
+			throw new Error(
+				"[echo] CacheManager singleton accessed before EchoProvider.boot() ran " +
+					"or `setCache(myCache)` was called. Wire one of them first.",
+			);
+		}
+		const value = Reflect.get(instance, prop, instance);
+		return typeof value === "function" ? value.bind(instance) : value;
+	},
+});
+
+export default cache;