@c9up/echo 0.1.5 → 0.1.7

package/dist/EchoProvider.d.ts

@@ -6,7 +6,7 @@ import { type CacheConfig } from "./CacheManager.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;
@@ -20,28 +20,34 @@ 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";
 }
 /**
- * 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 {
+    #private;
     protected app: EchoAppContext;
     constructor(app: EchoAppContext);
     register(): void;

package/dist/EchoProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EchoProvider.d.ts","sourceRoot":"","sources":["../src/EchoProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAgB,MAAM,mBAAmB,CAAC;AAInE;;;;GAIG;AACH,UAAU,aAAa;IACtB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;IACxD,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC;CACxC;AACD,UAAU,eAAe;IACxB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CAC7C;AACD,MAAM,WAAW,cAAc;IAC9B,SAAS,EAAE,aAAa,CAAC;IACzB,MAAM,EAAE,eAAe,CAAC;CACxB;AAED,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACtD;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,OAAO,OAAO,YAAY;IACpB,SAAS,CAAC,GAAG,EAAE,cAAc;gBAAnB,GAAG,EAAE,cAAc;IAEzC,QAAQ,IAAI,IAAI;IAiBV,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAC/B"}
+{"version":3,"file":"EchoProvider.d.ts","sourceRoot":"","sources":["../src/EchoProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAgB,MAAM,mBAAmB,CAAC;AAMnE;;;;GAIG;AACH,UAAU,aAAa;IACtB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;IACxD,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACjD;AACD,UAAU,eAAe;IACxB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CAC7C;AACD,MAAM,WAAW,cAAc;IAC9B,SAAS,EAAE,aAAa,CAAC;IACzB,MAAM,EAAE,eAAe,CAAC;CACxB;AAED,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACtD;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC;CAClB;AAmBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,OAAO,OAAO,YAAY;;IACpB,SAAS,CAAC,GAAG,EAAE,cAAc;gBAAnB,GAAG,EAAE,cAAc;IAYzC,QAAQ,IAAI,IAAI;IA0BV,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAC/B"}

package/dist/EchoProvider.js

@@ -1,40 +1,74 @@
 import { CacheManager } from "./CacheManager.js";
 import { MemoryDriver } from "./drivers/MemoryDriver.js";
+import { CacheStoreManager } from "./StoreManager.js";
 import { setCache } from "./services/main.js";
+function isEmitter(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof Reflect.get(value, "emit") === "function");
+}
+function isMultiStoreConfig(value) {
+    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 {
     app;
     constructor(app) {
         this.app = app;
     }
+    async #resolveEmitter() {
+        try {
+            const candidate = await this.app.container.resolve("emitter");
+            if (isEmitter(candidate))
+                return candidate;
+        }
+        catch {
+            // No emitter bound — events are simply not emitted.
+        }
+        return undefined;
+    }
     register() {
-        this.app.container.singleton(CacheManager, () => {
-            const config = this.app.config.get("cache");
-            const driver = config?.driver ?? "memory";
+        this.app.container.singleton(CacheManager, async () => {
+            const emitter = await this.#resolveEmitter();
+            const raw = this.app.config.get("cache");
+            if (isMultiStoreConfig(raw)) {
+                const manager = new CacheStoreManager({ ...raw, emitter });
+                return manager.use();
+            }
+            const config = (raw ?? {});
+            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));
     }
     async boot() {
-        setCache(this.app.container.resolve(CacheManager));
+        setCache(await this.app.container.resolve(CacheManager));
     }
     async shutdown() { }
 }

package/dist/EchoProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"EchoProvider.js","sourceRoot":"","sources":["../src/EchoProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AA+B9C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,OAAO,OAAO,YAAY;IACV;IAAtB,YAAsB,GAAmB;QAAnB,QAAG,GAAH,GAAG,CAAgB;IAAG,CAAC;IAE7C,QAAQ;QACP,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,YAAY,EAAE,GAAG,EAAE;YAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAqB,OAAO,CAAC,CAAC;YAChE,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,IAAI,QAAQ,CAAC;YAC1C,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CACd,8BAA8B,MAAM,2BAA2B;oBAC9D,oDAAoD,CACrD,CAAC;YACH,CAAC;YACD,OAAO,IAAI,YAAY,CAAC,IAAI,YAAY,EAAE,EAAE,MAAM,CAAC,CAAC;QACrD,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,EAAE,CAC1C,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAe,YAAY,CAAC,CACtD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI;QACT,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAe,YAAY,CAAC,CAAC,CAAC;IAClE,CAAC;IAED,KAAK,CAAC,QAAQ,KAAmB,CAAC;CAClC"}
+{"version":3,"file":"EchoProvider.js","sourceRoot":"","sources":["../src/EchoProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAyB,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAiC9C,SAAS,SAAS,CAAC,KAAc;IAChC,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,UAAU,CAChD,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACzC,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,QAAQ,IAAI,KAAK;QACjB,SAAS,IAAI,KAAK,CAClB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,OAAO,OAAO,YAAY;IACV;IAAtB,YAAsB,GAAmB;QAAnB,QAAG,GAAH,GAAG,CAAgB;IAAG,CAAC;IAE7C,KAAK,CAAC,eAAe;QACpB,IAAI,CAAC;YACJ,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAU,SAAS,CAAC,CAAC;YACvE,IAAI,SAAS,CAAC,SAAS,CAAC;gBAAE,OAAO,SAAS,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACR,oDAAoD;QACrD,CAAC;QACD,OAAO,SAAS,CAAC;IAClB,CAAC;IAED,QAAQ;QACP,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,YAAY,EAAE,KAAK,IAAI,EAAE;YACrD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC;YAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAU,OAAO,CAAC,CAAC;YAElD,IAAI,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7B,MAAM,OAAO,GAAG,IAAI,iBAAiB,CAAC,EAAE,GAAG,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;gBAC3D,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC;YACtB,CAAC;YAED,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,EAAE,CAAuB,CAAC;YACjD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,QAAQ,CAAC;YACzC,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CACd,8BAA8B,MAAM,2BAA2B;oBAC9D,gEAAgE;oBAChE,2CAA2C,CAC5C,CAAC;YACH,CAAC;YACD,OAAO,IAAI,YAAY,CAAC,IAAI,YAAY,EAAE,EAAE,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,EAAE,CAC1C,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAe,YAAY,CAAC,CACtD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI;QACT,QAAQ,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAe,YAAY,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,QAAQ,KAAmB,CAAC;CAClC"}

package/dist/StoreManager.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 { type RedisClient } from "./drivers/RedisDriver.js";
+import { type CacheBus } 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 declare const drivers: {
+    memory(options?: {
+        sweepIntervalMs?: number;
+    }): DriverFactory;
+    redis(options: {
+        client: RedisClient;
+        prefix?: string;
+    }): DriverFactory;
+    tiered(options: {
+        l1: DriverFactory;
+        l2: DriverFactory;
+        bus?: CacheBus;
+    }): DriverFactory;
+};
+export declare class CacheStoreManager {
+    #private;
+    constructor(config: MultiStoreConfig);
+    /** Resolve a store by name (or the default). Instances are built once and cached. */
+    use(name?: string): CacheManager;
+}
+//# sourceMappingURL=StoreManager.d.ts.map

package/dist/StoreManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StoreManager.d.ts","sourceRoot":"","sources":["../src/StoreManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,KAAK,WAAW,EAAe,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,KAAK,QAAQ,EAAgB,MAAM,2BAA2B,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5D,2EAA2E;AAC3E,MAAM,MAAM,aAAa,GAAG,MAAM,WAAW,CAAC;AAE9C,MAAM,WAAW,WAAW;IAC3B,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,WAAW,CAAC,EAAE,QAAQ,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACpC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,yEAAyE;AACzE,eAAO,MAAM,OAAO;qBACF;QAAE,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,aAAa;mBAG9C;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,aAAa;oBAGvD;QACf,EAAE,EAAE,aAAa,CAAC;QAClB,EAAE,EAAE,aAAa,CAAC;QAClB,GAAG,CAAC,EAAE,QAAQ,CAAC;KACf,GAAG,aAAa;CAQjB,CAAC;AAEF,qBAAa,iBAAiB;;gBAIjB,MAAM,EAAE,gBAAgB;IASpC,qFAAqF;IACrF,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,YAAY;CAsBhC"}

package/dist/StoreManager.js

@@ -0,0 +1,70 @@
+/**
+ * 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 { RedisDriver } from "./drivers/RedisDriver.js";
+import { TieredDriver } from "./drivers/TieredDriver.js";
+/** Driver factory helpers (bento `drivers.memory` / `drivers.redis`). */
+export const drivers = {
+    memory(options) {
+        return () => new MemoryDriver(options?.sweepIntervalMs);
+    },
+    redis(options) {
+        return () => new RedisDriver(options.client, options.prefix);
+    },
+    tiered(options) {
+        return () => new TieredDriver({
+            l1: options.l1(),
+            l2: options.l2(),
+            bus: options.bus,
+        });
+    },
+};
+export class CacheStoreManager {
+    #config;
+    #built = new Map();
+    constructor(config) {
+        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) {
+        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;
+    }
+}
+//# sourceMappingURL=StoreManager.js.map

package/dist/StoreManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StoreManager.js","sourceRoot":"","sources":["../src/StoreManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAoB,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAiB,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAyBxE,yEAAyE;AACzE,MAAM,CAAC,MAAM,OAAO,GAAG;IACtB,MAAM,CAAC,OAAsC;QAC5C,OAAO,GAAG,EAAE,CAAC,IAAI,YAAY,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IACzD,CAAC;IACD,KAAK,CAAC,OAAiD;QACtD,OAAO,GAAG,EAAE,CAAC,IAAI,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D,CAAC;IACD,MAAM,CAAC,OAIN;QACA,OAAO,GAAG,EAAE,CACX,IAAI,YAAY,CAAC;YAChB,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE;YAChB,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE;YAChB,GAAG,EAAE,OAAO,CAAC,GAAG;SAChB,CAAC,CAAC;IACL,CAAC;CACD,CAAC;AAEF,MAAM,OAAO,iBAAiB;IAC7B,OAAO,CAAmB;IAC1B,MAAM,GAA8B,IAAI,GAAG,EAAE,CAAC;IAE9C,YAAY,MAAwB;QACnC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CACd,wBAAwB,MAAM,CAAC,OAAO,4BAA4B,CAClE,CAAC;QACH,CAAC;IACF,CAAC;IAED,qFAAqF;IACrF,GAAG,CAAC,IAAa;QAChB,MAAM,KAAK,GAAG,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAE9B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,CAAC,GAAG,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,8BAA8B,KAAK,GAAG,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE;YAC9C,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,GAAG,EAAE,GAAG,CAAC,GAAG;YACZ,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,IAAI,EAAE,KAAK;YACX,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO;SAC7B,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAChC,OAAO,OAAO,CAAC;IAChB,CAAC;CACD"}

package/dist/drivers/MemoryDriver.d.ts

@@ -1,20 +1,27 @@
 /**
- * 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";
-export declare class MemoryDriver implements CacheDriver {
+import type { CacheEntry, DriverSetOptions, TaggableDriver } from "../types.js";
+export declare class MemoryDriver implements TaggableDriver {
     #private;
     constructor(sweepIntervalMs?: number);
     destroy(): void;
     get<T = unknown>(key: string): Promise<T | null>;
+    getEntry<T = unknown>(key: string): Promise<CacheEntry<T> | null>;
+    /** Synchronous read used by both `get` and `getEntry` (and by TieredDriver's L1 fast path). */
+    getEntrySync<T = unknown>(key: string): CacheEntry<T> | null;
     set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    setEntry(key: string, value: unknown, options: DriverSetOptions): Promise<void>;
     delete(key: string): Promise<boolean>;
     flush(): Promise<void>;
     has(key: string): Promise<boolean>;
-    /** Set with tags for group invalidation. */
+    /** Set with tags for group invalidation (bento parity; no grace). */
     setWithTags(key: string, value: unknown, tags: string[], ttlSeconds?: number): Promise<void>;
-    /** Flush all entries tagged with any of the given tags. */
+    /** Invalidate all entries tagged with any of the given tags. */
+    deleteByTag(tags: string[]): Promise<void>;
+    /** @deprecated alias of {@link deleteByTag}. */
     flushTags(tags: string[]): Promise<void>;
 }
 //# sourceMappingURL=MemoryDriver.d.ts.map

package/dist/drivers/MemoryDriver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemoryDriver.d.ts","sourceRoot":"","sources":["../../src/drivers/MemoryDriver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAQtD,qBAAa,YAAa,YAAW,WAAW;;gBAKnC,eAAe,SAAS;IAiBpC,OAAO,IAAI,IAAI;IAIT,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAqBhD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBpE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKxC,4CAA4C;IACtC,WAAW,CAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EAAE,EACd,UAAU,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IA+BhB,2DAA2D;IACrD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAgC9C"}
+{"version":3,"file":"MemoryDriver.d.ts","sourceRoot":"","sources":["../../src/drivers/MemoryDriver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAWhF,qBAAa,YAAa,YAAW,cAAc;;gBAKtC,eAAe,SAAS;IAiBpC,OAAO,IAAI,IAAI;IAIT,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAMhD,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAIvE,+FAA+F;IAC/F,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;IAqEtD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE,QAAQ,CACb,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,gBAAgB,GACvB,OAAO,CAAC,IAAI,CAAC;IAWV,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxC,qEAAqE;IAC/D,WAAW,CAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EAAE,EACd,UAAU,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IAIhB,gEAAgE;IAC1D,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBhD,gDAAgD;IAC1C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAG9C"}

package/dist/drivers/MemoryDriver.js

@@ -1,6 +1,7 @@
 /**
- * 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}.
  */
 export class MemoryDriver {
     #store = new Map();
@@ -10,7 +11,7 @@ export class MemoryDriver {
         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);
                 }
             }
@@ -24,40 +25,79 @@ export class MemoryDriver {
         clearInterval(this.#sweepInterval);
     }
     async get(key) {
+        const entry = this.getEntrySync(key);
+        if (entry === null || entry.stale)
+            return null;
+        return entry.value;
+    }
+    async getEntry(key) {
+        return this.getEntrySync(key);
+    }
+    /** Synchronous read used by both `get` and `getEntry` (and by TieredDriver's L1 fast path). */
+    getEntrySync(key) {
         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;
+        const stale = entry.expiresAt > 0 && entry.expiresAt < now;
+        return { value: entry.value, 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, entry) {
         for (const tag of entry.tags)
             this.#tagIndex.get(tag)?.delete(key);
         this.#store.delete(key);
     }
-    async set(key, value, ttlSeconds) {
+    #write(key, value, ttlSeconds, graceSeconds, tags, expiresAtOverride) {
         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;
-        // 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).
+        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 = 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, value, ttlSeconds) {
+        this.#write(key, value, ttlSeconds, 0, []);
+    }
+    async setEntry(key, value, options) {
+        this.#write(key, value, options.ttlSeconds, options.graceSeconds ?? 0, options.tags ?? [], options.expiresAt);
     }
     async delete(key) {
         const entry = this.#store.get(key);
@@ -73,52 +113,17 @@ export class MemoryDriver {
         this.#tagIndex.clear();
     }
     async has(key) {
-        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, value, tags, ttlSeconds) {
-        // 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) {
-        // 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) {
+        // 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();
         for (const tag of tags) {
             const keys = this.#tagIndex.get(tag);
@@ -136,11 +141,12 @@ export class MemoryDriver {
             }
             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) {
+        return this.deleteByTag(tags);
+    }
 }
 //# sourceMappingURL=MemoryDriver.js.map

package/dist/drivers/MemoryDriver.js.map

@@ -1 +1 @@
-{"version":3,"file":"MemoryDriver.js","sourceRoot":"","sources":["../../src/drivers/MemoryDriver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"MemoryDriver.js","sourceRoot":"","sources":["../../src/drivers/MemoryDriver.ts"],"names":[],"mappings":"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"}

package/dist/drivers/RedisDriver.d.ts

@@ -1,12 +1,17 @@
 /**
- * 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 {
     get(key: string): Promise<string | null>;
@@ -21,30 +26,25 @@ export interface RedisClient {
     ttl(key: string): Promise<number>;
     scan?(cursor: string, matchOption: "MATCH", pattern: string, countOption: "COUNT", count: number): Promise<[string, string[]]>;
 }
-export declare class RedisDriver implements CacheDriver {
+export declare class RedisDriver implements TaggableDriver {
     #private;
     constructor(client: RedisClient, prefix?: string);
     delete(key: string): Promise<boolean>;
     get<T = unknown>(key: string): Promise<T | null>;
+    getEntry<T = unknown>(key: string): Promise<CacheEntry<T> | null>;
     set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    setEntry(key: string, value: unknown, options: DriverSetOptions): Promise<void>;
     flush(): Promise<void>;
     has(key: string): Promise<boolean>;
-    /**
-     * 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.
-     */
+    /** Set a value with tag memberships for group invalidation (no grace). */
     setWithTags(key: string, value: unknown, tags: string[], ttlSeconds?: number): Promise<void>;
     /**
-     * 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.
      */
+    deleteByTag(tags: string[]): Promise<void>;
+    /** @deprecated alias of {@link deleteByTag}. */
     flushTags(tags: string[]): Promise<void>;
 }
 //# sourceMappingURL=RedisDriver.d.ts.map