@c9up/echo 0.1.5 → 0.1.7

package/src/drivers/RedisDriver.ts

@@ -1,13 +1,18 @@
 /**
- * Redis cache driver — production-grade cache with TTL and tags.
+ * Redis cache driver — production-grade cache with TTL, grace
+ * (stale-while-revalidate) and tags. Suitable as the L2 tier of
+ * {@link TieredDriver}.
  *
  * Requires a Redis client instance implementing the minimal interface below.
  * Compatible with ioredis and redis (node-redis) clients.
  *
- * @implements MISS-10
+ * STORAGE FORMAT (breaking vs echo <=0.1.5): values are stored as a JSON
+ * envelope `{ "v": <value>, "e": <logicalExpiryEpochMs> }`. The physical Redis
+ * TTL (`EX`) covers `ttl + grace` so a logically-expired value survives for the
+ * grace window; `e` records the logical expiry so reads can flag it stale.
  */
 
-import type { CacheDriver } from "../CacheManager.js";
+import type { CacheEntry, DriverSetOptions, TaggableDriver } from "../types.js";
 
 /** Minimal Redis client interface — compatible with ioredis and node-redis. */
 export interface RedisClient {
@@ -30,7 +35,22 @@ export interface RedisClient {
 	): Promise<[string, string[]]>;
 }
 
-export class RedisDriver implements CacheDriver {
+interface Envelope {
+	v: unknown;
+	e: number;
+}
+
+function isEnvelope(x: unknown): x is Envelope {
+	return (
+		typeof x === "object" &&
+		x !== null &&
+		"v" in x &&
+		"e" in x &&
+		typeof Reflect.get(x, "e") === "number"
+	);
+}
+
+export class RedisDriver implements TaggableDriver {
 	#client: RedisClient;
 	#prefix: string;
 
@@ -44,12 +64,9 @@ export class RedisDriver implements CacheDriver {
 	}
 
 	/**
-	 * 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.
+	 * Reverse-index for per-key tag membership. Lets tag writes clean stale
+	 * memberships on retag, and `delete()` drop the key from every tag-set it
+	 * belongs to.
 	 */
 	#metaKey(k: string): string {
 		return `${this.#prefix}meta:tags:${k}`;
@@ -71,29 +88,92 @@ export class RedisDriver implements CacheDriver {
 	}
 
 	async get<T = unknown>(key: string): Promise<T | null> {
+		const entry = await this.getEntry<T>(key);
+		if (entry === null || entry.stale) return null;
+		return entry.value;
+	}
+
+	async getEntry<T = unknown>(key: string): Promise<CacheEntry<T> | null> {
 		const raw = await this.#client.get(this.#key(key));
 		if (raw === null) return null;
-		return JSON.parse(raw) as T;
+		const parsed: unknown = JSON.parse(raw);
+		if (!isEnvelope(parsed)) return null;
+		const stale = parsed.e > 0 && parsed.e < Date.now();
+		// Deserialize boundary: the on-the-wire value is genuinely `unknown`; the
+		// caller's generic `T` is the assertion. This is the single unavoidable
+		// cast site (mirrors echo <=0.1.5 `JSON.parse(raw) as T`).
+		const value = parsed.v as T;
+		return { value, stale, expiresAt: parsed.e };
 	}
 
-	async set(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
-		const fullKey = this.#key(key);
-		// Reconcile tags: overwriting a previously-tagged key with an untagged
-		// value must drop it from its old tag sets + meta index, or a later
-		// flushTags would wrongly purge this fresh value (set() never touched the
-		// tag/meta keys, unlike delete()).
-		const metaKey = this.#metaKey(key);
+	/** Write the value envelope with a physical (grace-inclusive) TTL in seconds. */
+	async #writeEnvelope(
+		fullKey: string,
+		value: unknown,
+		logicalTtlSeconds: number,
+		physicalTtlSeconds: number,
+		logicalExpiresAtOverride?: number,
+	): Promise<void> {
+		// An absolute override (e.g. `expire()` marking stale-now) wins over the
+		// ttl-derived logical expiry; a past value flags the entry stale on read.
+		const expiresAt =
+			logicalExpiresAtOverride !== undefined
+				? logicalExpiresAtOverride
+				: logicalTtlSeconds > 0
+					? Date.now() + logicalTtlSeconds * 1000
+					: 0;
+		const envelope: Envelope = { v: value, e: expiresAt };
+		const serialized = JSON.stringify(envelope);
+		if (physicalTtlSeconds > 0) {
+			await this.#client.set(fullKey, serialized, "EX", physicalTtlSeconds);
+		} else {
+			await this.#client.set(fullKey, serialized);
+		}
+	}
+
+	/** Drop a key from its previous tag memberships (reconcile before re-tagging). */
+	async #dropTags(fullKey: string, metaKey: string): Promise<string[]> {
 		const prevTags = await this.#client.smembers(metaKey);
 		for (const tag of prevTags) {
 			await this.#client.srem(`${this.#prefix}tag:${tag}`, fullKey);
 		}
 		if (prevTags.length > 0) await this.#client.del(metaKey);
-		const serialized = JSON.stringify(value);
-		if (ttlSeconds && ttlSeconds > 0) {
-			await this.#client.set(fullKey, serialized, "EX", ttlSeconds);
-		} else {
-			await this.#client.set(fullKey, serialized);
+		return prevTags;
+	}
+
+	async set(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
+		const fullKey = this.#key(key);
+		await this.#dropTags(fullKey, this.#metaKey(key));
+		const ttl = ttlSeconds && ttlSeconds > 0 ? ttlSeconds : 0;
+		await this.#writeEnvelope(fullKey, value, ttl, ttl);
+	}
+
+	async setEntry(
+		key: string,
+		value: unknown,
+		options: DriverSetOptions,
+	): Promise<void> {
+		const fullKey = this.#key(key);
+		const metaKey = this.#metaKey(key);
+		const ttl =
+			options.ttlSeconds && options.ttlSeconds > 0 ? options.ttlSeconds : 0;
+		const grace =
+			options.graceSeconds && options.graceSeconds > 0
+				? options.graceSeconds
+				: 0;
+		// With an absolute logical expiry (e.g. `expire()` marking stale-now), the
+		// ttl no longer drives physical retention — keep the value for the grace
+		// window measured from now so a stale-but-graced read still finds it.
+		const override = options.expiresAt;
+		const physical = override !== undefined ? grace : ttl > 0 ? ttl + grace : 0;
+		const tags = options.tags ?? [];
+		if (tags.length === 0) {
+			await this.#dropTags(fullKey, metaKey);
+			await this.#writeEnvelope(fullKey, value, ttl, physical, override);
+			return;
 		}
+		await this.#writeEnvelope(fullKey, value, ttl, physical, override);
+		await this.#applyTags(key, tags, physical);
 	}
 
 	async flush(): Promise<void> {
@@ -121,25 +201,18 @@ export class RedisDriver implements CacheDriver {
 	}
 
 	async has(key: string): Promise<boolean> {
-		const exists = await this.#client.exists(this.#key(key));
-		return exists > 0;
+		return (await this.get(key)) !== null;
 	}
 
 	/**
-	 * 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.
+	 * Reconcile the tag reverse-index for `key` to exactly `tags`, and extend
+	 * tag-set / meta TTLs to the physical (grace-inclusive) retention.
 	 */
-	async setWithTags(
+	async #applyTags(
 		key: string,
-		value: unknown,
 		tags: string[],
-		ttlSeconds?: number,
+		physicalTtlSeconds: 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);
@@ -148,57 +221,56 @@ export class RedisDriver implements CacheDriver {
 		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);
+			await this.#client.srem(`${this.#prefix}tag:${tag}`, 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) {
+			if (physicalTtlSeconds > 0) {
 				const currentTtl = await this.#client.ttl(tagKey);
-				if (currentTtl < 0 || ttlSeconds > currentTtl) {
-					await this.#client.expire(tagKey, ttlSeconds);
+				if (currentTtl < 0 || physicalTtlSeconds > currentTtl) {
+					await this.#client.expire(tagKey, physicalTtlSeconds);
 				}
 			}
 		}
 
-		// 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);
+			if (physicalTtlSeconds > 0) {
+				await this.#client.expire(metaKey, physicalTtlSeconds);
 			}
 		}
 	}
 
+	/** Set a value with tag memberships for group invalidation (no grace). */
+	async setWithTags(
+		key: string,
+		value: unknown,
+		tags: string[],
+		ttlSeconds?: number,
+	): Promise<void> {
+		const ttl = ttlSeconds && ttlSeconds > 0 ? ttlSeconds : 0;
+		await this.#writeEnvelope(this.#key(key), value, ttl, ttl);
+		await this.#applyTags(key, tags, ttl);
+	}
+
 	/**
-	 * 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.
+	 * Invalidate all entries tagged with any of the given tags. Cleans the
+	 * per-key reverse-index AND cross-tag memberships so a multi-tag key flushed
+	 * via one tag is also removed from the others.
 	 */
-	async flushTags(tags: string[]): Promise<void> {
+	async deleteByTag(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;
@@ -219,4 +291,9 @@ export class RedisDriver implements CacheDriver {
 			await this.#client.del(tagKey);
 		}
 	}
+
+	/** @deprecated alias of {@link deleteByTag}. */
+	async flushTags(tags: string[]): Promise<void> {
+		return this.deleteByTag(tags);
+	}
 }

package/src/drivers/TieredDriver.ts

@@ -0,0 +1,186 @@
+/**
+ * TieredDriver — two-tier cache composing an L1 (in-process, e.g.
+ * {@link MemoryDriver}) and an L2 (distributed, e.g. {@link RedisDriver}).
+ *
+ * Reads go L1 → L2 → miss, promoting an L2 hit back into L1. Writes are
+ * write-through to both tiers. An optional {@link CacheBus} broadcasts
+ * invalidations so peer instances drop their (now stale) L1 copies — the L2 is
+ * shared, so only L1 needs cross-instance invalidation.
+ */
+
+import type {
+	CacheDriver,
+	CacheEntry,
+	DriverSetOptions,
+	TaggableDriver,
+} from "../types.js";
+
+/** A cross-instance invalidation message. */
+export interface BusMessage {
+	type: "delete" | "clear";
+	keys: string[];
+}
+
+/** Duck-typed pub/sub bus for cross-instance L1 invalidation (e.g. Redis pub/sub). */
+export interface CacheBus {
+	publish(message: BusMessage): void | Promise<void>;
+	subscribe(handler: (message: BusMessage) => void): void;
+}
+
+export interface TieredDriverOptions {
+	l1: CacheDriver;
+	l2: CacheDriver;
+	bus?: CacheBus;
+}
+
+function isTaggable(driver: CacheDriver): driver is TaggableDriver {
+	const candidate: Partial<TaggableDriver> = driver;
+	return (
+		typeof candidate.setWithTags === "function" &&
+		(typeof candidate.deleteByTag === "function" ||
+			typeof candidate.flushTags === "function")
+	);
+}
+
+async function readEntry<T>(
+	driver: CacheDriver,
+	key: string,
+): Promise<CacheEntry<T> | null> {
+	if (driver.getEntry) return driver.getEntry<T>(key);
+	const value = await driver.get<T>(key);
+	return value === null ? null : { value, stale: false };
+}
+
+async function writeEntry(
+	driver: CacheDriver,
+	key: string,
+	value: unknown,
+	options: DriverSetOptions,
+): Promise<void> {
+	if (driver.setEntry) {
+		await driver.setEntry(key, value, options);
+		return;
+	}
+	if (options.tags && options.tags.length > 0 && isTaggable(driver)) {
+		await driver.setWithTags(key, value, options.tags, options.ttlSeconds);
+		return;
+	}
+	await driver.set(key, value, options.ttlSeconds);
+}
+
+export class TieredDriver implements TaggableDriver {
+	#l1: CacheDriver;
+	#l2: CacheDriver;
+	#bus: CacheBus | undefined;
+
+	constructor(options: TieredDriverOptions) {
+		this.#l1 = options.l1;
+		this.#l2 = options.l2;
+		this.#bus = options.bus;
+		this.#bus?.subscribe((message) => {
+			// Peer invalidation: only the local L1 needs clearing (L2 is shared).
+			if (message.type === "clear") {
+				void this.#l1.flush();
+				return;
+			}
+			for (const key of message.keys) void this.#l1.delete(key);
+		});
+	}
+
+	async getEntry<T = unknown>(key: string): Promise<CacheEntry<T> | null> {
+		const l1 = await readEntry<T>(this.#l1, key);
+		if (l1 && !l1.stale) return l1;
+
+		const l2 = await readEntry<T>(this.#l2, key);
+		if (l2 && !l2.stale) {
+			// Promote a fresh L2 hit into L1 — preserving the remaining logical TTL
+			// so L1 cannot outlive L2 (a promotion with no TTL left an immortal L1
+			// entry that kept serving a value the L2 had already expired).
+			if (l2.expiresAt === undefined) {
+				// Driver doesn't expose expiry — promoting with no TTL risks an
+				// immortal L1 copy; skip promotion rather than cache it forever.
+				return l2;
+			}
+			const opts: DriverSetOptions = {};
+			if (l2.expiresAt > 0) {
+				const remainingSeconds = (l2.expiresAt - Date.now()) / 1000;
+				// Raced past expiry between the stale check and now — don't promote
+				// a value that is already dead.
+				if (remainingSeconds <= 0) return l2;
+				opts.ttlSeconds = remainingSeconds;
+			}
+			// expiresAt === 0 → the L2 entry genuinely never expires → promote as-is.
+			await writeEntry(this.#l1, key, l2.value, opts);
+			return l2;
+		}
+		if (l2) return l2; // stale L2 (grace)
+		if (l1) return l1; // stale L1 (grace)
+		return null;
+	}
+
+	async get<T = unknown>(key: string): Promise<T | null> {
+		const entry = await this.getEntry<T>(key);
+		if (entry === null || entry.stale) return null;
+		return entry.value;
+	}
+
+	async set(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
+		await this.setEntry(key, value, { ttlSeconds });
+	}
+
+	async setEntry(
+		key: string,
+		value: unknown,
+		options: DriverSetOptions,
+	): Promise<void> {
+		await writeEntry(this.#l1, key, value, options);
+		await writeEntry(this.#l2, key, value, options);
+		await this.#bus?.publish({ type: "delete", keys: [key] });
+	}
+
+	async delete(key: string): Promise<boolean> {
+		const l1 = await this.#l1.delete(key);
+		const l2 = await this.#l2.delete(key);
+		await this.#bus?.publish({ type: "delete", keys: [key] });
+		return l1 || l2;
+	}
+
+	async flush(): Promise<void> {
+		await this.#l1.flush();
+		await this.#l2.flush();
+		await this.#bus?.publish({ type: "clear", keys: [] });
+	}
+
+	async has(key: string): Promise<boolean> {
+		return (await this.get(key)) !== null;
+	}
+
+	async setWithTags(
+		key: string,
+		value: unknown,
+		tags: string[],
+		ttlSeconds?: number,
+	): Promise<void> {
+		await this.setEntry(key, value, { ttlSeconds, tags });
+	}
+
+	async deleteByTag(tags: string[]): Promise<void> {
+		const l1 = this.#l1;
+		const l2 = this.#l2;
+		if (!isTaggable(l1) || !isTaggable(l2)) {
+			throw new Error(
+				"Echo: TieredDriver.deleteByTag requires both tiers to be taggable",
+			);
+		}
+		await l1.deleteByTag(tags);
+		await l2.deleteByTag(tags);
+		// Peers can't map tags → keys locally; broadcast a clear so their L1 drops
+		// any tagged copies (conservative but correct).
+		await this.#bus?.publish({ type: "clear", keys: [] });
+	}
+
+	/** @deprecated alias of {@link deleteByTag}. */
+	async flushTags(tags: string[]): Promise<void> {
+		return this.deleteByTag(tags);
+	}
+}

package/src/duration.ts

@@ -0,0 +1,86 @@
+/**
+ * Duration parsing — bentocache `Duration` parity, adapted to echo's
+ * seconds-native driver layer.
+ *
+ * DIVERGENCE (named): bentocache treats a bare `number` as **milliseconds**.
+ * Echo's drivers, positional API (`set(key, value, ttlSeconds)`) and the
+ * kitchen-sink app are all **seconds-native**, so a bare `number` here means
+ * **seconds**. Keeping one unit across the positional and object forms avoids
+ * a dual-unit footgun (cf. DNR `helpers_no_magic_layer`). String durations use
+ * the same human syntax as bento (`'5m'`, `'300s'`, `'2h'`, `'500ms'`).
+ */
+
+/**
+ * A cache duration:
+ * - `number` — seconds (echo-native; see divergence note above)
+ * - `string` — human duration (`'5m'`, `'2h'`, `'1d'`, `'500ms'`, …)
+ * - `null`   — never expires
+ */
+export type Duration = number | string | null;
+
+const UNIT_SECONDS: Record<string, number> = {
+	ms: 1 / 1000,
+	msec: 1 / 1000,
+	msecs: 1 / 1000,
+	millisecond: 1 / 1000,
+	milliseconds: 1 / 1000,
+	s: 1,
+	sec: 1,
+	secs: 1,
+	second: 1,
+	seconds: 1,
+	m: 60,
+	min: 60,
+	mins: 60,
+	minute: 60,
+	minutes: 60,
+	h: 3600,
+	hr: 3600,
+	hrs: 3600,
+	hour: 3600,
+	hours: 3600,
+	d: 86_400,
+	day: 86_400,
+	days: 86_400,
+	w: 604_800,
+	week: 604_800,
+	weeks: 604_800,
+};
+
+const DURATION_RE = /^\s*(-?\d+(?:\.\d+)?)\s*([a-z]+)?\s*$/i;
+
+/**
+ * Parse a human duration string (`'5m'`, `'300s'`, `'500ms'`) into seconds.
+ * A unit-less numeric string is interpreted as seconds.
+ */
+export function parseDuration(value: string): number {
+	const match = DURATION_RE.exec(value);
+	if (!match) {
+		throw new TypeError(`Echo: invalid duration string "${value}"`);
+	}
+	const amount = Number(match[1]);
+	const unit = match[2]?.toLowerCase();
+	if (unit === undefined) return amount;
+	const factor = UNIT_SECONDS[unit];
+	if (factor === undefined) {
+		throw new TypeError(`Echo: unknown duration unit "${unit}" in "${value}"`);
+	}
+	return amount * factor;
+}
+
+/**
+ * Resolve a {@link Duration} to a TTL in **seconds**.
+ *
+ * @returns the TTL in seconds; `0` means "never expires" (either an explicit
+ *   `null`, or a non-positive value, matching echo's driver convention where
+ *   `ttlSeconds <= 0` is treated as immortal).
+ */
+export function resolveTtlSeconds(
+	ttl: Duration | undefined,
+	defaultSeconds: number,
+): number {
+	if (ttl === null) return 0;
+	if (ttl === undefined) return defaultSeconds;
+	const seconds = typeof ttl === "number" ? ttl : parseDuration(ttl);
+	return seconds > 0 ? seconds : 0;
+}

package/src/errors.ts

@@ -0,0 +1,33 @@
+/**
+ * Echo cache errors — bentocache parity (`errors.ts`).
+ */
+
+/** Raised when a factory exceeds its configured `hardTimeout`. */
+export class TimeoutError extends Error {
+	constructor(key: string, timeoutMs: number) {
+		super(`Echo: factory for "${key}" timed out after ${timeoutMs}ms`);
+		this.name = "TimeoutError";
+	}
+}
+
+/**
+ * Wraps an error thrown by a `getOrSet` factory. Passed to `onFactoryError`
+ * so callers can observe both foreground and background factory failures.
+ */
+export class FactoryError extends Error {
+	/** The cache key the factory was computing. */
+	readonly key: string;
+	/** The original error thrown by the factory. */
+	override readonly cause: unknown;
+	/** `true` when the factory was running in the background (soft timeout / refresh). */
+	readonly isBackground: boolean;
+
+	constructor(key: string, cause: unknown, isBackground: boolean) {
+		const reason = cause instanceof Error ? cause.message : String(cause);
+		super(`Echo: factory for "${key}" failed: ${reason}`);
+		this.name = "FactoryError";
+		this.key = key;
+		this.cause = cause;
+		this.isBackground = isBackground;
+	}
+}

package/src/index.ts

@@ -1,8 +1,10 @@
 /**
  * @c9up/echo — Cache layer for the Ream framework.
  *
- * Provides get/set/delete/clear/getOrSet/namespace/tags with pluggable drivers
- * (Memory, Redis).
+ * bentocache / @adonisjs/cache parity: object-argument API, grace
+ * (stale-while-revalidate), soft/hard timeouts, tags, multi-tier (L1+L2) and
+ * multi-store (`{ default, stores }` + `use(name)`) — over pluggable drivers
+ * (Memory, Redis, Tiered).
  *
  * @implements MISS-10
  */
@@ -12,14 +14,52 @@ export { CacheManager } from "./CacheManager.js";
 export { MemoryDriver } from "./drivers/MemoryDriver.js";
 export type { RedisClient } from "./drivers/RedisDriver.js";
 export { RedisDriver } from "./drivers/RedisDriver.js";
+export type {
+	BusMessage,
+	CacheBus,
+	TieredDriverOptions,
+} from "./drivers/TieredDriver.js";
+export { TieredDriver } from "./drivers/TieredDriver.js";
+export type { Duration } from "./duration.js";
+export { parseDuration, resolveTtlSeconds } from "./duration.js";
 export type { EchoProviderConfig } from "./EchoProvider.js";
+export { FactoryError, TimeoutError } from "./errors.js";
+export {
+	CacheStoreManager,
+	type DriverFactory,
+	drivers,
+	type MultiStoreConfig,
+	type StoreConfig,
+} from "./StoreManager.js";
+export type {
+	CacheEmitter,
+	CacheEntry,
+	CacheEventMap,
+	DefaultValue,
+	DeleteByTagOptions,
+	DeleteManyOptions,
+	DeleteOptions,
+	ExpireOptions,
+	Factory,
+	GetOptions,
+	GetOrSetForeverOptions,
+	GetOrSetOptions,
+	HasOptions,
+	SetOptions,
+	TaggableDriver,
+} from "./types.js";
 
 import type { EchoProviderConfig } from "./EchoProvider.js";
+import type { MultiStoreConfig } from "./StoreManager.js";
 
 /**
  * Author-time config helper for `config/cache.ts` — AdonisJS cache `defineConfig`
  * parity. Identity at runtime; the generic preserves literal types for inference.
+ * Accepts both the single-store {@link EchoProviderConfig} and the multi-store
+ * {@link MultiStoreConfig} (`{ default, stores }`) shapes.
  */
-export function defineConfig<T extends EchoProviderConfig>(config: T): T {
+export function defineConfig<T extends EchoProviderConfig | MultiStoreConfig>(
+	config: T,
+): T {
 	return config;
 }