@c9up/echo 0.1.3

package/dist/drivers/RedisDriver.js

@@ -0,0 +1,166 @@
+/**
+ * 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
+ */
+export class RedisDriver {
+    #client;
+    #prefix;
+    constructor(client, prefix = "cache:") {
+        this.#client = client;
+        this.#prefix = prefix;
+    }
+    #key(k) {
+        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) {
+        return `${this.#prefix}meta:tags:${k}`;
+    }
+    async delete(key) {
+        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(key) {
+        const raw = await this.#client.get(this.#key(key));
+        if (raw === null)
+            return null;
+        return JSON.parse(raw);
+    }
+    async set(key, value, ttlSeconds) {
+        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() {
+        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) {
+        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, value, tags, ttlSeconds) {
+        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) {
+        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);
+        }
+    }
+}
+//# sourceMappingURL=RedisDriver.js.map

package/dist/drivers/RedisDriver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisDriver.js","sourceRoot":"","sources":["../../src/drivers/RedisDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAyBH,MAAM,OAAO,WAAW;IACvB,OAAO,CAAc;IACrB,OAAO,CAAS;IAEhB,YAAY,MAAmB,EAAE,MAAM,GAAG,QAAQ;QACjD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,IAAI,CAAC,CAAS;QACb,OAAO,GAAG,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;IAC9B,CAAC;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,CAAS;QACjB,OAAO,GAAG,IAAI,CAAC,OAAO,aAAa,CAAC,EAAE,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACvB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAClD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACxB,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,OAAO,GAAG,EAAE,CAAC;YAC3C,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC9C,OAAO,KAAK,GAAG,CAAC,CAAC;IAClB,CAAC;IAED,KAAK,CAAC,GAAG,CAAc,GAAW;QACjC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACnD,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAc,EAAE,UAAmB;QACzD,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,UAAU,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;QACtE,CAAC;aAAM,CAAC;YACP,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC,CAAC;QACpD,CAAC;IACF,CAAC;IAED,KAAK,CAAC,KAAK;QACV,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;QAC/B,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;YAChC,IAAI,MAAM,GAAG,GAAG,CAAC;YACjB,GAAG,CAAC;gBACH,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,MAAM,IAAI,CACpC,MAAM,EACN,OAAO,EACP,GAAG,IAAI,CAAC,OAAO,GAAG,EAClB,OAAO,EACP,GAAG,CACH,CAAC;gBACF,MAAM,GAAG,UAAU,CAAC;gBACpB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACrB,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBAC9B,CAAC;YACF,CAAC,QAAQ,MAAM,KAAK,GAAG,EAAE;QAC1B,CAAC;aAAM,CAAC;YACP,MAAM,IAAI,KAAK,CACd,uGAAuG,CACvG,CAAC;QACH,CAAC;IACF,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACpB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACzD,OAAO,MAAM,GAAG,CAAC,CAAC;IACnB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,WAAW,CAChB,GAAW,EACX,KAAc,EACd,IAAc,EACd,UAAmB;QAEnB,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACrD,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QACnC,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAExD,sDAAsD;QACtD,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YAC/B,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,OAAO,GAAG,EAAE,CAAC;YAC3C,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC1C,CAAC;QAED,uEAAuE;QACvE,0CAA0C;QAC1C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACxB,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,OAAO,GAAG,EAAE,CAAC;YAC3C,IAAI,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7B,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC1C,CAAC;YACD,IAAI,UAAU,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;gBAClC,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBAClD,IAAI,UAAU,GAAG,CAAC,IAAI,UAAU,GAAG,UAAU,EAAE,CAAC;oBAC/C,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;gBAC/C,CAAC;YACF,CAAC;QACF,CAAC;QAED,qEAAqE;QACrE,qEAAqE;QACrE,2BAA2B;QAC3B,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;YAC1C,IAAI,UAAU,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;gBAClC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAChD,CAAC;QACF,CAAC;IACF,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,SAAS,CAAC,IAAc;QAC7B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACxB,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,OAAO,GAAG,EAAE,CAAC;YAC3C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACpD,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;gBAC/B,+DAA+D;gBAC/D,4DAA4D;gBAC5D,6DAA6D;gBAC7D,UAAU;gBACV,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;oBAC/C,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;oBACpC,CAAC,CAAC,OAAO,CAAC;gBACX,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;gBACvC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;gBACrD,KAAK,MAAM,QAAQ,IAAI,OAAO,EAAE,CAAC;oBAChC,IAAI,QAAQ,KAAK,GAAG;wBAAE,SAAS;oBAC/B,MAAM,WAAW,GAAG,GAAG,IAAI,CAAC,OAAO,OAAO,QAAQ,EAAE,CAAC;oBACrD,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;gBAC/C,CAAC;gBACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACxB,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBACjC,CAAC;YACF,CAAC;YACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACjC,CAAC;YACD,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAChC,CAAC;IACF,CAAC;CACD"}

package/dist/index.d.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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,YAAY,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

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

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/services/main.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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";
+/** @internal Bind the singleton (called by EchoProvider or by the app). */
+export declare function setCache(value: CacheManager): void;
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export declare function getCache(): CacheManager | undefined;
+declare const cache: CacheManager;
+export default cache;
+//# sourceMappingURL=main.d.ts.map

package/dist/services/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/services/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAElD;AAED,8DAA8D;AAC9D,wBAAgB,QAAQ,IAAI,YAAY,GAAG,SAAS,CAEnD;AAED,QAAA,MAAM,KAAK,EAAE,YAWX,CAAC;AAEH,eAAe,KAAK,CAAC"}

package/dist/services/main.js

@@ -0,0 +1,33 @@
+/**
+ * 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')
+ */
+let instance;
+/** @internal Bind the singleton (called by EchoProvider or by the app). */
+export function setCache(value) {
+    instance = value;
+}
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export function getCache() {
+    return instance;
+}
+const cache = new Proxy({}, {
+    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;
+//# sourceMappingURL=main.js.map

package/dist/services/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/services/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,IAAI,QAAkC,CAAC;AAEvC,2EAA2E;AAC3E,MAAM,UAAU,QAAQ,CAAC,KAAmB;IAC3C,QAAQ,GAAG,KAAK,CAAC;AAClB,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,QAAQ;IACvB,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED,MAAM,KAAK,GAAiB,IAAI,KAAK,CAAC,EAAkB,EAAE;IACzD,GAAG,CAAC,OAAO,EAAE,IAAI;QAChB,IAAI,CAAC,QAAQ,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACd,wEAAwE;gBACvE,4DAA4D,CAC7D,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACpD,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACnE,CAAC;CACD,CAAC,CAAC;AAEH,eAAe,KAAK,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@c9up/echo",
+  "version": "0.1.3",
+  "description": "Cache — pluggable cache contract with memory + Redis drivers for the Ream framework",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./provider": {
+      "types": "./dist/EchoProvider.d.ts",
+      "import": "./dist/EchoProvider.js"
+    },
+    "./services/main": {
+      "types": "./dist/services/main.d.ts",
+      "import": "./dist/services/main.js"
+    }
+  },
+  "peerDependencies": {
+    "@c9up/ream": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependenciesMeta": {
+    "@c9up/ream": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/C9up/echo.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "lint": "biome check src/",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/CacheManager.ts

@@ -0,0 +1,150 @@
+/**
+ * CacheManager — unified cache API with driver abstraction.
+ */
+
+export interface CacheDriver {
+	get<T = unknown>(key: string): Promise<T | null>;
+	set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+	delete(key: string): Promise<boolean>;
+	flush(): Promise<void>;
+	has(key: string): Promise<boolean>;
+}
+
+interface TaggableDriver extends CacheDriver {
+	setWithTags(
+		key: string,
+		value: unknown,
+		tags: string[],
+		ttlSeconds?: number,
+	): Promise<void>;
+	flushTags(tags: string[]): Promise<void>;
+}
+
+function isTaggableDriver(driver: CacheDriver): driver is TaggableDriver {
+	const candidate = driver as Partial<TaggableDriver>;
+	return (
+		typeof candidate.flushTags === "function" &&
+		typeof candidate.setWithTags === "function"
+	);
+}
+
+export interface CacheConfig {
+	driver?: string;
+	prefix?: string;
+	ttl?: number;
+}
+
+export class CacheManager implements CacheDriver {
+	private driver: CacheDriver;
+	private prefix: string;
+	private defaultTtl: number;
+
+	constructor(driver: CacheDriver, config?: CacheConfig) {
+		this.driver = driver;
+		this.prefix = config?.prefix ?? "";
+		this.defaultTtl = config?.ttl ?? 3600;
+	}
+
+	private prefixKey(key: string): string {
+		return this.prefix ? `${this.prefix}:${key}` : key;
+	}
+
+	async get<T = unknown>(key: string): Promise<T | null> {
+		return this.driver.get<T>(this.prefixKey(key));
+	}
+
+	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",
+			);
+		}
+		return this.driver.set(
+			this.prefixKey(key),
+			value,
+			ttlSeconds ?? this.defaultTtl,
+		);
+	}
+
+	async delete(key: string): Promise<boolean> {
+		return this.driver.delete(this.prefixKey(key));
+	}
+
+	async flush(): Promise<void> {
+		return this.driver.flush();
+	}
+
+	async has(key: string): Promise<boolean> {
+		return this.driver.has(this.prefixKey(key));
+	}
+
+	/** Set a value with tags for grouped invalidation. */
+	async setWithTags(
+		key: string,
+		value: unknown,
+		tags: string[],
+		ttlSeconds?: number,
+	): Promise<void> {
+		if (value === null || value === undefined) {
+			throw new TypeError(
+				"Echo: caching null/undefined values is not supported",
+			);
+		}
+		if (!isTaggableDriver(this.driver)) {
+			throw new Error(
+				"Echo: the configured driver does not support tag-based invalidation",
+			);
+		}
+		return this.driver.setWithTags(
+			this.prefixKey(key),
+			value,
+			tags,
+			ttlSeconds ?? this.defaultTtl,
+		);
+	}
+
+	/** Flush only entries with matching tags. */
+	async flushTags(tags: string[]): Promise<void> {
+		if (isTaggableDriver(this.driver)) {
+			return this.driver.flushTags(tags);
+		}
+		throw new Error(
+			"Echo: the configured driver does not support tag-based invalidation",
+		);
+	}
+
+	/** In-flight promises for stampede prevention. Each factory is typed per-call; the map is keyed by prefixed cache key. */
+	private inflight: Map<string, Promise<unknown>> = new Map();
+
+	/** Get or set — fetch from cache, or compute and store. Single-flight: concurrent misses share one factory call. */
+	async remember<T>(
+		key: string,
+		ttl: number,
+		factory: () => Promise<T>,
+	): Promise<T> {
+		const prefixed = this.prefixKey(key);
+
+		const existing = this.inflight.get(prefixed);
+		if (existing) return existing.then((v) => v as T);
+
+		const cached = await this.get<T>(key);
+		if (cached !== null) return cached;
+
+		const existingAfterAwait = this.inflight.get(prefixed);
+		if (existingAfterAwait) return existingAfterAwait.then((v) => v as T);
+
+		const promise: Promise<T> = factory()
+			.then(async (value) => {
+				await this.set(key, value, ttl);
+				this.inflight.delete(prefixed);
+				return value;
+			})
+			.catch((err) => {
+				this.inflight.delete(prefixed);
+				throw err;
+			});
+
+		this.inflight.set(prefixed, promise);
+		return promise;
+	}
+}

package/src/EchoProvider.ts

@@ -0,0 +1,74 @@
+import { type CacheConfig, CacheManager } from "./CacheManager.js";
+import { MemoryDriver } from "./drivers/MemoryDriver.js";
+import { setCache } from "./services/main.js";
+
+/**
+ * Duck-typed host context — echo stays publishable without importing
+ * `@c9up/ream`. Any framework that exposes a Container + a config
+ * store satisfies the contract.
+ */
+interface EchoContainer {
+	singleton(token: unknown, factory: () => unknown): void;
+	resolve<T = unknown>(token: unknown): T;
+}
+interface EchoConfigStore {
+	get<T = unknown>(key: string): T | undefined;
+}
+export interface EchoAppContext {
+	container: EchoContainer;
+	config: EchoConfigStore;
+}
+
+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`.
+	 *
+	 * 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.
+ *
+ *   // reamrc.ts
+ *   providers: [() => import('@c9up/echo/provider')]
+ *
+ *   // config/cache.ts
+ *   export default { driver: 'memory', prefix: 'myapp', ttl: 300 }
+ *
+ *   // anywhere
+ *   import cache from '@c9up/echo/services/main'
+ *   await cache.set('k', v, 60)
+ */
+export default class EchoProvider {
+	constructor(protected app: EchoAppContext) {}
+
+	register(): void {
+		this.app.container.singleton(CacheManager, () => {
+			const config = this.app.config.get<EchoProviderConfig>("cache");
+			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.",
+				);
+			}
+			return new CacheManager(new MemoryDriver(), config);
+		});
+		this.app.container.singleton("cache", () =>
+			this.app.container.resolve<CacheManager>(CacheManager),
+		);
+	}
+
+	async boot(): Promise<void> {
+		setCache(this.app.container.resolve<CacheManager>(CacheManager));
+	}
+
+	async shutdown(): Promise<void> {}
+}