@c9up/echo 0.1.5 → 0.1.7

package/src/EchoProvider.ts

@@ -1,6 +1,8 @@
 import { type CacheConfig, CacheManager } from "./CacheManager.js";
 import { MemoryDriver } from "./drivers/MemoryDriver.js";
+import { CacheStoreManager, type MultiStoreConfig } from "./StoreManager.js";
 import { setCache } from "./services/main.js";
+import type { CacheEmitter } from "./types.js";
 
 /**
  * Duck-typed host context — echo stays publishable without importing
@@ -9,7 +11,7 @@ import { setCache } from "./services/main.js";
  */
 interface EchoContainer {
 	singleton(token: unknown, factory: () => unknown): void;
-	resolve<T = unknown>(token: unknown): T;
+	resolve<T = unknown>(token: unknown): Promise<T>;
 }
 interface EchoConfigStore {
 	get<T = unknown>(key: string): T | undefined;
@@ -24,42 +26,83 @@ export interface EchoProviderConfig extends CacheConfig {
 	 * Driver to bind by default. Only `"memory"` is created
 	 * automatically — other drivers (Redis etc.) need custom client
 	 * wiring, so apps build the `CacheManager` themselves and call
-	 * `setCache(...)` from `@c9up/echo/services/main`.
+	 * `setCache(...)` from `@c9up/echo/services/main`, or use the
+	 * multi-store `{ default, stores }` config with `drivers.*`.
 	 *
 	 * Default `"memory"`.
 	 */
 	driver?: "memory";
 }
 
+function isEmitter(value: unknown): value is CacheEmitter {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		typeof Reflect.get(value, "emit") === "function"
+	);
+}
+
+function isMultiStoreConfig(value: unknown): value is MultiStoreConfig {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"stores" in value &&
+		"default" in value
+	);
+}
+
 /**
- * EchoProvider — registers a default in-memory `CacheManager` so apps
- * that don't need Redis can `import cache from '@c9up/echo/services/main'`
- * and `await cache.get(...)` straight away.
+ * EchoProvider — registers a `CacheManager` (single-store default, or the
+ * default store of a `{ default, stores }` config) so apps can
+ * `import cache from '@c9up/echo/services/main'` and use it straight away. If
+ * the host container exposes an `emitter`, cache events (`cache:hit` / `miss` /
+ * `written` / `deleted` / `cleared`) are wired through it.
  *
  *   // reamrc.ts
  *   providers: [() => import('@c9up/echo/provider')]
  *
- *   // config/cache.ts
+ *   // config/cache.ts  (single store)
  *   export default { driver: 'memory', prefix: 'myapp', ttl: 300 }
  *
- *   // anywhere
- *   import cache from '@c9up/echo/services/main'
- *   await cache.set('k', v, 60)
+ *   // config/cache.ts  (multi-store)
+ *   export default defineConfig({
+ *     default: 'memory',
+ *     stores: { memory: { driver: drivers.memory() } },
+ *   })
  */
 export default class EchoProvider {
 	constructor(protected app: EchoAppContext) {}
 
+	async #resolveEmitter(): Promise<CacheEmitter | undefined> {
+		try {
+			const candidate = await this.app.container.resolve<unknown>("emitter");
+			if (isEmitter(candidate)) return candidate;
+		} catch {
+			// No emitter bound — events are simply not emitted.
+		}
+		return undefined;
+	}
+
 	register(): void {
-		this.app.container.singleton(CacheManager, () => {
-			const config = this.app.config.get<EchoProviderConfig>("cache");
-			const driver = config?.driver ?? "memory";
+		this.app.container.singleton(CacheManager, async () => {
+			const emitter = await this.#resolveEmitter();
+			const raw = this.app.config.get<unknown>("cache");
+
+			if (isMultiStoreConfig(raw)) {
+				const manager = new CacheStoreManager({ ...raw, emitter });
+				return manager.use();
+			}
+
+			const config = (raw ?? {}) as EchoProviderConfig;
+			const driver = config.driver ?? "memory";
 			if (driver !== "memory") {
 				throw new Error(
 					`[echo] Unsupported driver '${driver}' for default provider — ` +
-						"wire CacheManager yourself for non-memory drivers.",
+						"wire CacheManager yourself for non-memory drivers, or use the " +
+						"multi-store `{ default, stores }` config.",
 				);
 			}
-			return new CacheManager(new MemoryDriver(), config);
+			return new CacheManager(new MemoryDriver(), { ...config, emitter });
 		});
 		this.app.container.singleton("cache", () =>
 			this.app.container.resolve<CacheManager>(CacheManager),
@@ -67,7 +110,7 @@ export default class EchoProvider {
 	}
 
 	async boot(): Promise<void> {
-		setCache(this.app.container.resolve<CacheManager>(CacheManager));
+		setCache(await this.app.container.resolve<CacheManager>(CacheManager));
 	}
 
 	async shutdown(): Promise<void> {}

package/src/StoreManager.ts

@@ -0,0 +1,104 @@
+/**
+ * Multi-store cache manager — `{ default, stores }` config + `cache.use(name)`
+ * (bentocache `BentoCache` / @adonisjs/cache parity), plus the `drivers.*`
+ * factory helpers.
+ *
+ *   const cache = new CacheStoreManager(defineConfig({
+ *     default: "memory",
+ *     stores: {
+ *       memory: { driver: drivers.memory() },
+ *       redis:  { driver: drivers.redis({ client }) },
+ *     },
+ *   }))
+ *
+ *   await cache.use().set({ key: "k", value: 1 })      // default store
+ *   await cache.use("redis").get({ key: "k" })         // named store
+ */
+
+import { CacheManager } from "./CacheManager.js";
+import { MemoryDriver } from "./drivers/MemoryDriver.js";
+import { type RedisClient, RedisDriver } from "./drivers/RedisDriver.js";
+import { type CacheBus, TieredDriver } from "./drivers/TieredDriver.js";
+import type { Duration } from "./duration.js";
+import type { CacheDriver, CacheEmitter } from "./types.js";
+
+/** A lazily-instantiated driver (built once per store, on first `use`). */
+export type DriverFactory = () => CacheDriver;
+
+export interface StoreConfig {
+	driver: DriverFactory;
+	prefix?: string;
+	/** Default TTL in seconds. */
+	ttl?: number;
+	grace?: Duration;
+	timeout?: Duration;
+	hardTimeout?: Duration;
+	lockTimeout?: Duration;
+}
+
+export interface MultiStoreConfig {
+	default: string;
+	stores: Record<string, StoreConfig>;
+	/** Shared emitter for all stores' events. */
+	emitter?: CacheEmitter;
+}
+
+/** Driver factory helpers (bento `drivers.memory` / `drivers.redis`). */
+export const drivers = {
+	memory(options?: { sweepIntervalMs?: number }): DriverFactory {
+		return () => new MemoryDriver(options?.sweepIntervalMs);
+	},
+	redis(options: { client: RedisClient; prefix?: string }): DriverFactory {
+		return () => new RedisDriver(options.client, options.prefix);
+	},
+	tiered(options: {
+		l1: DriverFactory;
+		l2: DriverFactory;
+		bus?: CacheBus;
+	}): DriverFactory {
+		return () =>
+			new TieredDriver({
+				l1: options.l1(),
+				l2: options.l2(),
+				bus: options.bus,
+			});
+	},
+};
+
+export class CacheStoreManager {
+	#config: MultiStoreConfig;
+	#built: Map<string, CacheManager> = new Map();
+
+	constructor(config: MultiStoreConfig) {
+		this.#config = config;
+		if (!config.stores[config.default]) {
+			throw new Error(
+				`Echo: default store "${config.default}" is not defined in stores`,
+			);
+		}
+	}
+
+	/** Resolve a store by name (or the default). Instances are built once and cached. */
+	use(name?: string): CacheManager {
+		const store = name ?? this.#config.default;
+		const existing = this.#built.get(store);
+		if (existing) return existing;
+
+		const cfg = this.#config.stores[store];
+		if (!cfg) {
+			throw new Error(`Echo: unknown cache store "${store}"`);
+		}
+		const manager = new CacheManager(cfg.driver(), {
+			prefix: cfg.prefix,
+			ttl: cfg.ttl,
+			grace: cfg.grace,
+			timeout: cfg.timeout,
+			hardTimeout: cfg.hardTimeout,
+			lockTimeout: cfg.lockTimeout,
+			name: store,
+			emitter: this.#config.emitter,
+		});
+		this.#built.set(store, manager);
+		return manager;
+	}
+}

package/src/drivers/MemoryDriver.ts

@@ -1,18 +1,22 @@
 /**
- * Memory cache driver — in-process Map with TTL support.
- * Suitable for development and single-process deployments.
+ * Memory cache driver — in-process Map with TTL, grace (stale-while-revalidate)
+ * and tag support. Suitable for development and single-process deployments, and
+ * as the L1 tier of {@link TieredDriver}.
  */
 
-import type { CacheDriver } from "../CacheManager.js";
+import type { CacheEntry, DriverSetOptions, TaggableDriver } from "../types.js";
 
-interface CacheEntry {
+interface StoredEntry {
 	value: unknown;
+	/** Logical expiry (epoch ms); `0` means never. Past this the entry is stale. */
 	expiresAt: number;
+	/** Physical eviction (epoch ms); `0` means never. Grace window ends here. */
+	staleUntil: number;
 	tags: string[];
 }
 
-export class MemoryDriver implements CacheDriver {
-	#store: Map<string, CacheEntry> = new Map();
+export class MemoryDriver implements TaggableDriver {
+	#store: Map<string, StoredEntry> = new Map();
 	#tagIndex: Map<string, Set<string>> = new Map();
 	#sweepInterval: ReturnType<typeof setInterval>;
 
@@ -20,7 +24,7 @@ export class MemoryDriver implements CacheDriver {
 		this.#sweepInterval = setInterval(() => {
 			const now = Date.now();
 			for (const [key, entry] of this.#store) {
-				if (entry.expiresAt > 0 && entry.expiresAt < now) {
+				if (entry.staleUntil > 0 && entry.staleUntil < now) {
 					this.#evict(key, entry);
 				}
 			}
@@ -38,42 +42,102 @@ export class MemoryDriver implements CacheDriver {
 	}
 
 	async get<T = unknown>(key: string): Promise<T | null> {
+		const entry = this.getEntrySync<T>(key);
+		if (entry === null || entry.stale) return null;
+		return entry.value;
+	}
+
+	async getEntry<T = unknown>(key: string): Promise<CacheEntry<T> | null> {
+		return this.getEntrySync<T>(key);
+	}
+
+	/** Synchronous read used by both `get` and `getEntry` (and by TieredDriver's L1 fast path). */
+	getEntrySync<T = unknown>(key: string): CacheEntry<T> | null {
 		const entry = this.#store.get(key);
 		if (!entry) return null;
-		if (entry.expiresAt > 0 && entry.expiresAt < Date.now()) {
+		const now = Date.now();
+		if (entry.staleUntil > 0 && entry.staleUntil < now) {
 			this.#evict(key, entry);
 			return null;
 		}
-		return entry.value as T;
+		const stale = entry.expiresAt > 0 && entry.expiresAt < now;
+		return { value: entry.value as T, stale, expiresAt: entry.expiresAt };
 	}
 
 	/**
-	 * Delete an entry AND scrub its tag-index refs. TTL expiry (sweep + lazy
-	 * get) must go through this — a bare `#store.delete` left dangling refs in
-	 * `#tagIndex`, which a later `set(key, vNew)` reusing the key would turn into
-	 * a wrong-purge under flushTags (audit 2026-06-13).
+	 * Delete an entry AND scrub its tag-index refs. TTL/grace expiry (sweep +
+	 * lazy get) must go through this — a bare `#store.delete` left dangling refs
+	 * in `#tagIndex`, which a later `set(key, vNew)` reusing the key would turn
+	 * into a wrong-purge under deleteByTag (audit 2026-06-13).
 	 */
-	#evict(key: string, entry: CacheEntry): void {
+	#evict(key: string, entry: StoredEntry): void {
 		for (const tag of entry.tags) this.#tagIndex.get(tag)?.delete(key);
 		this.#store.delete(key);
 	}
 
-	async set(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
+	#write(
+		key: string,
+		value: unknown,
+		ttlSeconds: number | undefined,
+		graceSeconds: number,
+		tags: string[],
+		expiresAtOverride?: number,
+	): void {
 		if (value === null || value === undefined) {
 			throw new TypeError(
 				"Echo: caching null/undefined values is not supported",
 			);
 		}
+		const now = Date.now();
+		const hasTtl = ttlSeconds != null && ttlSeconds > 0;
+		// An absolute `expiresAtOverride` (e.g. `expire()` marking stale-now) wins
+		// over the ttl-derived expiry; a past value makes the entry immediately stale.
 		const expiresAt =
-			ttlSeconds != null && ttlSeconds > 0 ? Date.now() + ttlSeconds * 1000 : 0;
-		// Reconcile the tag index: overwriting a previously-tagged key with an
-		// untagged value must drop its old tag-index refs, or a later flushTags
-		// would purge this fresh value (the F3 fix only covered setWithTags).
+			expiresAtOverride !== undefined
+				? expiresAtOverride
+				: hasTtl
+					? now + ttlSeconds * 1000
+					: 0;
+		const graceMs = graceSeconds > 0 ? graceSeconds * 1000 : 0;
+		// A never-expiring entry never goes stale either; otherwise grace extends
+		// physical retention past the logical expiry. Measure grace from the LATER
+		// of the expiry and now, so an already-past expiry still survives its grace.
+		const staleUntil = expiresAt > 0 ? Math.max(expiresAt, now) + graceMs : 0;
+		// Reconcile the tag index: overwriting a previously-tagged key must drop
+		// its old tag-index refs, or a later deleteByTag could purge this fresh
+		// value (audit 2026-05-22 F3).
 		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: [] });
+		this.#store.set(key, { value, expiresAt, staleUntil, 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);
+		}
+	}
+
+	async set(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
+		this.#write(key, value, ttlSeconds, 0, []);
+	}
+
+	async setEntry(
+		key: string,
+		value: unknown,
+		options: DriverSetOptions,
+	): Promise<void> {
+		this.#write(
+			key,
+			value,
+			options.ttlSeconds,
+			options.graceSeconds ?? 0,
+			options.tags ?? [],
+			options.expiresAt,
+		);
 	}
 
 	async delete(key: string): Promise<boolean> {
@@ -92,59 +156,24 @@ export class MemoryDriver implements CacheDriver {
 	}
 
 	async has(key: string): Promise<boolean> {
-		const val = await this.get(key);
-		return val !== null;
+		return (await this.get(key)) !== null;
 	}
 
-	/** Set with tags for group invalidation. */
+	/** Set with tags for group invalidation (bento parity; no grace). */
 	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);
-		}
+		this.#write(key, value, ttlSeconds, 0, tags);
 	}
 
-	/** 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).
+	/** Invalidate all entries tagged with any of the given tags. */
+	async deleteByTag(tags: string[]): Promise<void> {
+		// Audit 2026-05-22 F3: scrub each key from EVERY tag set it belongs to
+		// (including tags not being flushed this round), else a multi-tagged key
+		// leaves a dangling ref that later wrong-purges a reused key.
 		const toDelete = new Set<string>();
 		for (const tag of tags) {
 			const keys = this.#tagIndex.get(tag);
@@ -161,9 +190,11 @@ export class MemoryDriver implements CacheDriver {
 			}
 			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);
 	}
+
+	/** @deprecated alias of {@link deleteByTag}. */
+	async flushTags(tags: string[]): Promise<void> {
+		return this.deleteByTag(tags);
+	}
 }