@iskra-bun/cache-kit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# @iskra-bun/cache-kit
+
+## 0.1.0
+
+### Minor Changes
+
+- f9654df: Initial public release. Higher-level application cache built on `@iskra-bun/kv-kit`: cache-aside (`remember`/`wrap`), TTL, namespaces, and tag-based invalidation, with an in-memory default and Redis support via a kv adapter.
+
+### Patch Changes
+
+- Updated dependencies [f9654df]
+- Updated dependencies
+- Updated dependencies [f9654df]
+- Updated dependencies [f9654df]
+- Updated dependencies
+- Updated dependencies [f9654df]
+    - @iskra-bun/core@0.1.1
+    - @iskra-bun/kv-kit@0.2.0

package/README.md

@@ -0,0 +1,51 @@
+# @iskra-bun/cache-kit
+
+Cache de aplicación de alto nivel para Iskra, construido sobre `@iskra-bun/kv-kit`.
+
+## Instalacion
+
+```bash
+bun add @iskra-bun/cache-kit @iskra-bun/kv-kit @iskra-bun/core
+```
+
+## Uso rapido
+
+```typescript
+import { Cache } from '@iskra-bun/cache-kit';
+
+// Zero-config — usa memoria en desarrollo
+const cache = new Cache();
+
+await cache.set('user:1', { name: 'Alice' }, { ttl: 300 });
+const user = await cache.get('user:1');
+
+// Cache-aside: llama al fallback solo en miss
+const data = await cache.remember('dashboard', 60, () => fetchFromDB());
+```
+
+## Namespacing
+
+```typescript
+const users = cache.namespace('users');
+const posts = cache.namespace('posts');
+
+await users.set('profile:1', userPayload);
+await posts.set('profile:1', postPayload); // clave distinta, sin colision
+```
+
+## Invalidacion por etiquetas
+
+```typescript
+await cache.set('item:1', item, { ttl: 60, tags: ['items', 'featured'] });
+await cache.set('item:2', item2, { ttl: 60, tags: ['items'] });
+
+await cache.invalidateTag('items'); // elimina item:1 e item:2
+```
+
+## Documentacion
+
+Guia completa: [docs/cache-kit.md](../../docs/cache-kit.md)
+
+## Licencia
+
+AGPL-3.0-or-later

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import { KVAdapter } from '@iskra-bun/kv-kit';
+
+interface CacheOptions {
+    /** Prefix prepended to every key — prevents collisions between modules. */
+    namespace?: string;
+    /** Default TTL in seconds applied when set() is called without an explicit ttl. */
+    defaultTtl?: number;
+}
+interface SetOptions {
+    /** TTL in seconds. Overrides any defaultTtl configured on the Cache. */
+    ttl?: number;
+    /**
+     * Tag names associated with this entry.
+     *
+     * Pass one or more tags so the entry can later be invalidated as a group
+     * via `Cache.invalidateTag(tag)`.
+     */
+    tags?: string[];
+}
+
+/**
+ * Cache — higher-level application cache backed by any {@link KVAdapter}.
+ *
+ * Works out of the box with zero config (defaults to an in-memory adapter).
+ * Compose with any kv-kit adapter (MemoryAdapter, RedisAdapter) for production.
+ *
+ * @example
+ * ```ts
+ * const cache = new Cache();
+ * await cache.set('user:1', { name: 'Alice' }, { ttl: 300 });
+ * const user = await cache.get<User>('user:1');
+ *
+ * // Cache-aside pattern
+ * const data = await cache.remember('expensive', 60, () => fetchFromDB());
+ *
+ * // Namespace isolation
+ * const userCache = cache.namespace('users');
+ * const postCache = cache.namespace('posts');
+ *
+ * // Tag-based invalidation
+ * await cache.set('item:1', data, { ttl: 60, tags: ['items'] });
+ * await cache.invalidateTag('items'); // removes all tagged entries
+ * ```
+ */
+declare class Cache {
+    private readonly adapter;
+    private readonly prefix;
+    private readonly defaultTtl;
+    constructor(adapter?: KVAdapter, options?: CacheOptions);
+    private prefixKey;
+    private tagIndexKey;
+    /**
+     * Retrieve a cached value by key.
+     * Returns `undefined` when the key is absent or has expired.
+     */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /**
+     * Store a value under key, optionally with a TTL and/or tags.
+     *
+     * @param key     Cache key (namespace prefix is applied automatically).
+     * @param value   Any JSON-serialisable value.
+     * @param options `ttl` in seconds and/or `tags` for group invalidation.
+     *                A bare number is treated as `ttl` seconds (shorthand).
+     */
+    set<T>(key: string, value: T, options?: number | SetOptions): Promise<void>;
+    /**
+     * Check whether a key exists in the cache (and has not expired).
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Delete a single key from the cache.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Flush the **entire** backing store shared by this Cache and every other
+     * Cache built on the same adapter.
+     *
+     * Implementation note: the {@link KVAdapter} interface does not expose key
+     * enumeration, so this recycles the adapter via `disconnect()`/`connect()`,
+     * which is a whole-store reset rather than a namespace-scoped one. To avoid
+     * a namespaced sub-cache silently nuking its siblings, this method refuses
+     * to run when a namespace prefix is set: it is only valid on a root Cache.
+     *
+     * @throws Error when called on a namespaced Cache (a prefix is set).
+     */
+    clear(): Promise<void>;
+    /**
+     * Return the cached value for `key` if present; otherwise call `fallback`,
+     * store the result with the given TTL, and return it.
+     *
+     * The fallback is called **exactly once** on a cache miss — never on a hit.
+     *
+     * @param key      Cache key.
+     * @param ttl      TTL in seconds for the stored value.
+     * @param fallback Async factory invoked on a cache miss.
+     */
+    remember<T>(key: string, ttl: number, fallback: () => Promise<T>): Promise<T>;
+    /** Alias for {@link remember}. */
+    readonly wrap: <T>(key: string, ttl: number, fallback: () => Promise<T>) => Promise<T>;
+    /**
+     * Invalidate every cached entry that was stored with the given tag.
+     *
+     * After this call all keys associated with `tag` are deleted and the tag
+     * index entry is removed. Entries carrying other tags are unaffected.
+     */
+    invalidateTag(tag: string): Promise<void>;
+    /**
+     * Return a new `Cache` sharing the same backing adapter but with an
+     * additional namespace prefix, preventing key collisions between modules.
+     *
+     * @example
+     * ```ts
+     * const users = cache.namespace('users');
+     * const posts = cache.namespace('posts');
+     * // 'users:profile:1' and 'posts:profile:1' are distinct keys
+     * ```
+     */
+    namespace(prefix: string): Cache;
+    private resolveSetOptions;
+    private indexTags;
+}
+
+export { Cache, type CacheOptions, type SetOptions };

package/dist/index.js

@@ -0,0 +1,261 @@
+// src/memory-adapter.ts
+var MemoryAdapter = class {
+  id = "memory";
+  store = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Map();
+  connect() {
+  }
+  disconnect() {
+    for (const timer of this.timers.values()) clearTimeout(timer);
+    this.timers = /* @__PURE__ */ new Map();
+    this.store = /* @__PURE__ */ new Map();
+  }
+  async get(key) {
+    return this.store.get(key);
+  }
+  async set(key, value, ttl) {
+    this.clearTimer(key);
+    this.store.set(key, value);
+    if (ttl) {
+      const timer = setTimeout(() => {
+        this.store.delete(key);
+        this.timers.delete(key);
+      }, ttl * 1e3);
+      timer.unref?.();
+      this.timers.set(key, timer);
+    }
+  }
+  async del(key) {
+    this.clearTimer(key);
+    this.store.delete(key);
+  }
+  clearTimer(key) {
+    const existing = this.timers.get(key);
+    if (existing) {
+      clearTimeout(existing);
+      this.timers.delete(key);
+    }
+  }
+  async has(key) {
+    return this.store.has(key);
+  }
+};
+
+// src/cache.ts
+var TAG_INDEX_PREFIX = "__cache_tag__:";
+var DANGEROUS_KEYS = ["__proto__", "constructor", "prototype"];
+function assertNoPollution(raw, value) {
+  if (DANGEROUS_KEYS.some((k) => raw.includes(`"${k}"`))) {
+    for (const key of DANGEROUS_KEYS) {
+      if (containsKey(value, key)) {
+        throw new Error(
+          `cache-kit: refusing to deserialize value containing the unsafe key "${key}" (prototype-pollution risk).`
+        );
+      }
+    }
+  }
+}
+function containsKey(value, key) {
+  if (value === null || typeof value !== "object") return false;
+  if (Object.prototype.hasOwnProperty.call(value, key)) return true;
+  return Object.values(value).some(
+    (child) => containsKey(child, key)
+  );
+}
+var Cache = class _Cache {
+  adapter;
+  prefix;
+  defaultTtl;
+  constructor(adapter, options = {}) {
+    this.adapter = adapter ?? new MemoryAdapter();
+    this.prefix = options.namespace ? `${options.namespace}:` : "";
+    this.defaultTtl = options.defaultTtl;
+  }
+  // -------------------------------------------------------------------------
+  // Key helpers
+  // -------------------------------------------------------------------------
+  prefixKey(key) {
+    return `${this.prefix}${key}`;
+  }
+  tagIndexKey(tag) {
+    return `${this.prefix}${TAG_INDEX_PREFIX}${tag}`;
+  }
+  // -------------------------------------------------------------------------
+  // Core API
+  // -------------------------------------------------------------------------
+  /**
+   * Retrieve a cached value by key.
+   * Returns `undefined` when the key is absent or has expired.
+   */
+  async get(key) {
+    const raw = await this.adapter.get(this.prefixKey(key));
+    if (raw === void 0 || raw === null) return void 0;
+    const text = raw;
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new Error(
+        `cache-kit: failed to deserialize value for key "${key}". The stored value is not valid JSON.`
+      );
+    }
+    assertNoPollution(text, parsed);
+    return parsed;
+  }
+  /**
+   * Store a value under key, optionally with a TTL and/or tags.
+   *
+   * @param key     Cache key (namespace prefix is applied automatically).
+   * @param value   Any JSON-serialisable value.
+   * @param options `ttl` in seconds and/or `tags` for group invalidation.
+   *                A bare number is treated as `ttl` seconds (shorthand).
+   */
+  async set(key, value, options) {
+    const { ttl, tags } = this.resolveSetOptions(options);
+    const serialized = JSON.stringify(value);
+    const effectiveTtl = ttl ?? this.defaultTtl;
+    await this.adapter.set(this.prefixKey(key), serialized, effectiveTtl);
+    if (tags && tags.length > 0) {
+      await this.indexTags(key, tags);
+    }
+  }
+  /**
+   * Check whether a key exists in the cache (and has not expired).
+   */
+  async has(key) {
+    return this.adapter.has(this.prefixKey(key));
+  }
+  /**
+   * Delete a single key from the cache.
+   */
+  async delete(key) {
+    await this.adapter.del(this.prefixKey(key));
+  }
+  /**
+   * Flush the **entire** backing store shared by this Cache and every other
+   * Cache built on the same adapter.
+   *
+   * Implementation note: the {@link KVAdapter} interface does not expose key
+   * enumeration, so this recycles the adapter via `disconnect()`/`connect()`,
+   * which is a whole-store reset rather than a namespace-scoped one. To avoid
+   * a namespaced sub-cache silently nuking its siblings, this method refuses
+   * to run when a namespace prefix is set: it is only valid on a root Cache.
+   *
+   * @throws Error when called on a namespaced Cache (a prefix is set).
+   */
+  async clear() {
+    if (this.prefix !== "") {
+      const namespace = this.prefix.replace(/:$/, "");
+      throw new Error(
+        `cache-kit: clear() resets the entire shared backing store and cannot be called on the namespaced cache "${namespace}". Delete individual keys with delete(), invalidate a group with invalidateTag(), or call clear() on the root cache to reset everything.`
+      );
+    }
+    await this.adapter.disconnect();
+    await this.adapter.connect();
+  }
+  // -------------------------------------------------------------------------
+  // Cache-aside (remember / wrap)
+  // -------------------------------------------------------------------------
+  /**
+   * Return the cached value for `key` if present; otherwise call `fallback`,
+   * store the result with the given TTL, and return it.
+   *
+   * The fallback is called **exactly once** on a cache miss — never on a hit.
+   *
+   * @param key      Cache key.
+   * @param ttl      TTL in seconds for the stored value.
+   * @param fallback Async factory invoked on a cache miss.
+   */
+  async remember(key, ttl, fallback) {
+    const cached = await this.get(key);
+    if (cached !== void 0) return cached;
+    let value;
+    try {
+      value = await fallback();
+    } catch (error) {
+      throw new Error(
+        `cache-kit: remember() fallback for key "${key}" threw: ${String(error)}`
+      );
+    }
+    await this.set(key, value, { ttl });
+    return value;
+  }
+  /** Alias for {@link remember}. */
+  wrap = this.remember.bind(this);
+  // -------------------------------------------------------------------------
+  // Tag-based invalidation
+  // -------------------------------------------------------------------------
+  /**
+   * Invalidate every cached entry that was stored with the given tag.
+   *
+   * After this call all keys associated with `tag` are deleted and the tag
+   * index entry is removed. Entries carrying other tags are unaffected.
+   */
+  async invalidateTag(tag) {
+    const indexKey = this.tagIndexKey(tag);
+    const raw = await this.adapter.get(indexKey);
+    if (raw === null || raw === void 0) return;
+    let keys;
+    try {
+      keys = JSON.parse(raw);
+    } catch {
+      keys = [];
+    }
+    await Promise.all([
+      ...keys.map((k) => this.adapter.del(this.prefixKey(k))),
+      this.adapter.del(indexKey)
+    ]);
+  }
+  // -------------------------------------------------------------------------
+  // Namespace helper
+  // -------------------------------------------------------------------------
+  /**
+   * Return a new `Cache` sharing the same backing adapter but with an
+   * additional namespace prefix, preventing key collisions between modules.
+   *
+   * @example
+   * ```ts
+   * const users = cache.namespace('users');
+   * const posts = cache.namespace('posts');
+   * // 'users:profile:1' and 'posts:profile:1' are distinct keys
+   * ```
+   */
+  namespace(prefix) {
+    const parentNs = this.prefix.replace(/:$/, "");
+    const combinedPrefix = parentNs ? `${parentNs}:${prefix}` : prefix;
+    return new _Cache(this.adapter, {
+      namespace: combinedPrefix,
+      defaultTtl: this.defaultTtl
+    });
+  }
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
+  resolveSetOptions(options) {
+    if (options === void 0) return {};
+    if (typeof options === "number") return { ttl: options };
+    return options;
+  }
+  async indexTags(key, tags) {
+    await Promise.all(
+      tags.map(async (tag) => {
+        const indexKey = this.tagIndexKey(tag);
+        const raw = await this.adapter.get(indexKey);
+        let keys = [];
+        if (raw !== null && raw !== void 0) {
+          try {
+            keys = JSON.parse(raw);
+          } catch {
+            keys = [];
+          }
+        }
+        const updated = keys.includes(key) ? keys : [...keys, key];
+        await this.adapter.set(indexKey, JSON.stringify(updated));
+      })
+    );
+  }
+};
+export {
+  Cache
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/memory-adapter.ts","../src/cache.ts"],"sourcesContent":["import type { KVAdapter } from './types';\n\n/**\n * Lightweight in-memory {@link KVAdapter} used as the default backing store\n * when no adapter is supplied to the {@link Cache} constructor.\n *\n * This is intentionally a thin Map wrapper — it mirrors kv-kit's MemoryAdapter\n * without depending on an unexported internal symbol.\n */\nexport class MemoryAdapter implements KVAdapter {\n    readonly id = 'memory';\n    private store = new Map<string, unknown>();\n    private timers = new Map<string, ReturnType<typeof setTimeout>>();\n\n    connect(): void {\n        // no-op\n    }\n\n    disconnect(): void {\n        for (const timer of this.timers.values()) clearTimeout(timer);\n        this.timers = new Map();\n        this.store = new Map();\n    }\n\n    async get<T = unknown>(key: string): Promise<T | undefined> {\n        return this.store.get(key) as T | undefined;\n    }\n\n    async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {\n        this.clearTimer(key);\n        this.store.set(key, value);\n        if (ttl) {\n            const timer = setTimeout(() => {\n                this.store.delete(key);\n                this.timers.delete(key);\n            }, ttl * 1000);\n            timer.unref?.();\n            this.timers.set(key, timer);\n        }\n    }\n\n    async del(key: string): Promise<void> {\n        this.clearTimer(key);\n        this.store.delete(key);\n    }\n\n    private clearTimer(key: string): void {\n        const existing = this.timers.get(key);\n        if (existing) {\n            clearTimeout(existing);\n            this.timers.delete(key);\n        }\n    }\n\n    async has(key: string): Promise<boolean> {\n        return this.store.has(key);\n    }\n}\n","import { MemoryAdapter } from './memory-adapter';\nimport type { KVAdapter, CacheOptions, SetOptions } from './types';\n\n/** Internal prefix used for the tag→keys index stored in the KV adapter. */\nconst TAG_INDEX_PREFIX = '__cache_tag__:';\n\n/** Keys that enable prototype-pollution when an object is later deep-merged. */\nconst DANGEROUS_KEYS = ['__proto__', 'constructor', 'prototype'] as const;\n\n/**\n * Throw if `value` (or any nested object) carries a prototype-pollution key.\n *\n * Cached payloads can originate from untrusted writers; rejecting these keys at\n * the parse boundary stops a malicious value from reaching code that deep-merges\n * it. Reads the raw JSON text first so `__proto__` (which `JSON.parse` hides on\n * the resulting object) is detected before traversal.\n */\nfunction assertNoPollution(raw: string, value: unknown): void {\n    if (DANGEROUS_KEYS.some((k) => raw.includes(`\"${k}\"`))) {\n        for (const key of DANGEROUS_KEYS) {\n            if (containsKey(value, key)) {\n                throw new Error(\n                    `cache-kit: refusing to deserialize value containing the ` +\n                    `unsafe key \"${key}\" (prototype-pollution risk).`\n                );\n            }\n        }\n    }\n}\n\n/** Recursively test whether `value` is/contains an object with own `key`. */\nfunction containsKey(value: unknown, key: string): boolean {\n    if (value === null || typeof value !== 'object') return false;\n    if (Object.prototype.hasOwnProperty.call(value, key)) return true;\n    return Object.values(value as Record<string, unknown>).some((child) =>\n        containsKey(child, key)\n    );\n}\n\n/**\n * Cache — higher-level application cache backed by any {@link KVAdapter}.\n *\n * Works out of the box with zero config (defaults to an in-memory adapter).\n * Compose with any kv-kit adapter (MemoryAdapter, RedisAdapter) for production.\n *\n * @example\n * ```ts\n * const cache = new Cache();\n * await cache.set('user:1', { name: 'Alice' }, { ttl: 300 });\n * const user = await cache.get<User>('user:1');\n *\n * // Cache-aside pattern\n * const data = await cache.remember('expensive', 60, () => fetchFromDB());\n *\n * // Namespace isolation\n * const userCache = cache.namespace('users');\n * const postCache = cache.namespace('posts');\n *\n * // Tag-based invalidation\n * await cache.set('item:1', data, { ttl: 60, tags: ['items'] });\n * await cache.invalidateTag('items'); // removes all tagged entries\n * ```\n */\nexport class Cache {\n    private readonly adapter: KVAdapter;\n    private readonly prefix: string;\n    private readonly defaultTtl: number | undefined;\n\n    constructor(adapter?: KVAdapter, options: CacheOptions = {}) {\n        this.adapter = adapter ?? new MemoryAdapter();\n        this.prefix = options.namespace ? `${options.namespace}:` : '';\n        this.defaultTtl = options.defaultTtl;\n    }\n\n    // -------------------------------------------------------------------------\n    // Key helpers\n    // -------------------------------------------------------------------------\n\n    private prefixKey(key: string): string {\n        return `${this.prefix}${key}`;\n    }\n\n    private tagIndexKey(tag: string): string {\n        return `${this.prefix}${TAG_INDEX_PREFIX}${tag}`;\n    }\n\n    // -------------------------------------------------------------------------\n    // Core API\n    // -------------------------------------------------------------------------\n\n    /**\n     * Retrieve a cached value by key.\n     * Returns `undefined` when the key is absent or has expired.\n     */\n    async get<T = unknown>(key: string): Promise<T | undefined> {\n        const raw = await this.adapter.get(this.prefixKey(key));\n        if (raw === undefined || raw === null) return undefined;\n\n        const text = raw as string;\n        let parsed: unknown;\n        try {\n            parsed = JSON.parse(text);\n        } catch {\n            throw new Error(\n                `cache-kit: failed to deserialize value for key \"${key}\". ` +\n                'The stored value is not valid JSON.'\n            );\n        }\n\n        assertNoPollution(text, parsed);\n        return parsed as T;\n    }\n\n    /**\n     * Store a value under key, optionally with a TTL and/or tags.\n     *\n     * @param key     Cache key (namespace prefix is applied automatically).\n     * @param value   Any JSON-serialisable value.\n     * @param options `ttl` in seconds and/or `tags` for group invalidation.\n     *                A bare number is treated as `ttl` seconds (shorthand).\n     */\n    async set<T>(key: string, value: T, options?: number | SetOptions): Promise<void> {\n        const { ttl, tags } = this.resolveSetOptions(options);\n        const serialized = JSON.stringify(value);\n        const effectiveTtl = ttl ?? this.defaultTtl;\n\n        await this.adapter.set(this.prefixKey(key), serialized, effectiveTtl);\n\n        if (tags && tags.length > 0) {\n            await this.indexTags(key, tags);\n        }\n    }\n\n    /**\n     * Check whether a key exists in the cache (and has not expired).\n     */\n    async has(key: string): Promise<boolean> {\n        return this.adapter.has(this.prefixKey(key));\n    }\n\n    /**\n     * Delete a single key from the cache.\n     */\n    async delete(key: string): Promise<void> {\n        await this.adapter.del(this.prefixKey(key));\n    }\n\n    /**\n     * Flush the **entire** backing store shared by this Cache and every other\n     * Cache built on the same adapter.\n     *\n     * Implementation note: the {@link KVAdapter} interface does not expose key\n     * enumeration, so this recycles the adapter via `disconnect()`/`connect()`,\n     * which is a whole-store reset rather than a namespace-scoped one. To avoid\n     * a namespaced sub-cache silently nuking its siblings, this method refuses\n     * to run when a namespace prefix is set: it is only valid on a root Cache.\n     *\n     * @throws Error when called on a namespaced Cache (a prefix is set).\n     */\n    async clear(): Promise<void> {\n        if (this.prefix !== '') {\n            const namespace = this.prefix.replace(/:$/, '');\n            throw new Error(\n                `cache-kit: clear() resets the entire shared backing store and ` +\n                `cannot be called on the namespaced cache \"${namespace}\". ` +\n                'Delete individual keys with delete(), invalidate a group with ' +\n                'invalidateTag(), or call clear() on the root cache to reset everything.'\n            );\n        }\n        await this.adapter.disconnect();\n        await this.adapter.connect();\n    }\n\n    // -------------------------------------------------------------------------\n    // Cache-aside (remember / wrap)\n    // -------------------------------------------------------------------------\n\n    /**\n     * Return the cached value for `key` if present; otherwise call `fallback`,\n     * store the result with the given TTL, and return it.\n     *\n     * The fallback is called **exactly once** on a cache miss — never on a hit.\n     *\n     * @param key      Cache key.\n     * @param ttl      TTL in seconds for the stored value.\n     * @param fallback Async factory invoked on a cache miss.\n     */\n    async remember<T>(key: string, ttl: number, fallback: () => Promise<T>): Promise<T> {\n        const cached = await this.get<T>(key);\n        if (cached !== undefined) return cached;\n\n        let value: T;\n        try {\n            value = await fallback();\n        } catch (error) {\n            throw new Error(\n                `cache-kit: remember() fallback for key \"${key}\" threw: ${String(error)}`\n            );\n        }\n\n        await this.set(key, value, { ttl });\n        return value;\n    }\n\n    /** Alias for {@link remember}. */\n    readonly wrap = this.remember.bind(this);\n\n    // -------------------------------------------------------------------------\n    // Tag-based invalidation\n    // -------------------------------------------------------------------------\n\n    /**\n     * Invalidate every cached entry that was stored with the given tag.\n     *\n     * After this call all keys associated with `tag` are deleted and the tag\n     * index entry is removed. Entries carrying other tags are unaffected.\n     */\n    async invalidateTag(tag: string): Promise<void> {\n        const indexKey = this.tagIndexKey(tag);\n        const raw = await this.adapter.get(indexKey);\n        if (raw === null || raw === undefined) return;\n\n        let keys: string[];\n        try {\n            keys = JSON.parse(raw as string) as string[];\n        } catch {\n            keys = [];\n        }\n\n        await Promise.all([\n            ...keys.map((k) => this.adapter.del(this.prefixKey(k))),\n            this.adapter.del(indexKey),\n        ]);\n    }\n\n    // -------------------------------------------------------------------------\n    // Namespace helper\n    // -------------------------------------------------------------------------\n\n    /**\n     * Return a new `Cache` sharing the same backing adapter but with an\n     * additional namespace prefix, preventing key collisions between modules.\n     *\n     * @example\n     * ```ts\n     * const users = cache.namespace('users');\n     * const posts = cache.namespace('posts');\n     * // 'users:profile:1' and 'posts:profile:1' are distinct keys\n     * ```\n     */\n    namespace(prefix: string): Cache {\n        const parentNs = this.prefix.replace(/:$/, '');\n        const combinedPrefix = parentNs ? `${parentNs}:${prefix}` : prefix;\n        return new Cache(this.adapter, {\n            namespace: combinedPrefix,\n            defaultTtl: this.defaultTtl,\n        });\n    }\n\n    // -------------------------------------------------------------------------\n    // Private helpers\n    // -------------------------------------------------------------------------\n\n    private resolveSetOptions(options?: number | SetOptions): SetOptions {\n        if (options === undefined) return {};\n        if (typeof options === 'number') return { ttl: options };\n        return options;\n    }\n\n    private async indexTags(key: string, tags: string[]): Promise<void> {\n        await Promise.all(\n            tags.map(async (tag) => {\n                const indexKey = this.tagIndexKey(tag);\n                const raw = await this.adapter.get(indexKey);\n                let keys: string[] = [];\n                if (raw !== null && raw !== undefined) {\n                    try {\n                        keys = JSON.parse(raw as string) as string[];\n                    } catch {\n                        keys = [];\n                    }\n                }\n                const updated = keys.includes(key) ? keys : [...keys, key];\n                await this.adapter.set(indexKey, JSON.stringify(updated));\n            })\n        );\n    }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,56 @@
+{
+    "name": "@iskra-bun/cache-kit",
+    "version": "0.1.0",
+    "description": "Cache de aplicación de alto nivel para Iskra, construido sobre @iskra-bun/kv-kit.",
+    "keywords": [
+        "iskra",
+        "bun",
+        "cache",
+        "cache-aside",
+        "ttl",
+        "kv"
+    ],
+    "author": "Joan Lascano",
+    "license": "AGPL-3.0-or-later",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/fearful/iskra.git",
+        "directory": "packages/cache-kit"
+    },
+    "homepage": "https://github.com/fearful/iskra/tree/main/packages/cache-kit#readme",
+    "bugs": "https://github.com/fearful/iskra/issues",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "source": "./src/index.ts",
+            "bun": "./src/index.ts",
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md",
+        "CHANGELOG.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "test": "bun test",
+        "build": "tsup --config ../../tsup.config.ts"
+    },
+    "dependencies": {
+        "@iskra-bun/core": "0.1.1",
+        "@iskra-bun/kv-kit": "0.2.0"
+    },
+    "devDependencies": {
+        "@types/bun": "^1.3.5",
+        "@types/node": "^22.10.2"
+    }
+}

package/src/cache.ts

@@ -0,0 +1,288 @@
+import { MemoryAdapter } from './memory-adapter';
+import type { KVAdapter, CacheOptions, SetOptions } from './types';
+
+/** Internal prefix used for the tag→keys index stored in the KV adapter. */
+const TAG_INDEX_PREFIX = '__cache_tag__:';
+
+/** Keys that enable prototype-pollution when an object is later deep-merged. */
+const DANGEROUS_KEYS = ['__proto__', 'constructor', 'prototype'] as const;
+
+/**
+ * Throw if `value` (or any nested object) carries a prototype-pollution key.
+ *
+ * Cached payloads can originate from untrusted writers; rejecting these keys at
+ * the parse boundary stops a malicious value from reaching code that deep-merges
+ * it. Reads the raw JSON text first so `__proto__` (which `JSON.parse` hides on
+ * the resulting object) is detected before traversal.
+ */
+function assertNoPollution(raw: string, value: unknown): void {
+    if (DANGEROUS_KEYS.some((k) => raw.includes(`"${k}"`))) {
+        for (const key of DANGEROUS_KEYS) {
+            if (containsKey(value, key)) {
+                throw new Error(
+                    `cache-kit: refusing to deserialize value containing the ` +
+                    `unsafe key "${key}" (prototype-pollution risk).`
+                );
+            }
+        }
+    }
+}
+
+/** Recursively test whether `value` is/contains an object with own `key`. */
+function containsKey(value: unknown, key: string): boolean {
+    if (value === null || typeof value !== 'object') return false;
+    if (Object.prototype.hasOwnProperty.call(value, key)) return true;
+    return Object.values(value as Record<string, unknown>).some((child) =>
+        containsKey(child, key)
+    );
+}
+
+/**
+ * Cache — higher-level application cache backed by any {@link KVAdapter}.
+ *
+ * Works out of the box with zero config (defaults to an in-memory adapter).
+ * Compose with any kv-kit adapter (MemoryAdapter, RedisAdapter) for production.
+ *
+ * @example
+ * ```ts
+ * const cache = new Cache();
+ * await cache.set('user:1', { name: 'Alice' }, { ttl: 300 });
+ * const user = await cache.get<User>('user:1');
+ *
+ * // Cache-aside pattern
+ * const data = await cache.remember('expensive', 60, () => fetchFromDB());
+ *
+ * // Namespace isolation
+ * const userCache = cache.namespace('users');
+ * const postCache = cache.namespace('posts');
+ *
+ * // Tag-based invalidation
+ * await cache.set('item:1', data, { ttl: 60, tags: ['items'] });
+ * await cache.invalidateTag('items'); // removes all tagged entries
+ * ```
+ */
+export class Cache {
+    private readonly adapter: KVAdapter;
+    private readonly prefix: string;
+    private readonly defaultTtl: number | undefined;
+
+    constructor(adapter?: KVAdapter, options: CacheOptions = {}) {
+        this.adapter = adapter ?? new MemoryAdapter();
+        this.prefix = options.namespace ? `${options.namespace}:` : '';
+        this.defaultTtl = options.defaultTtl;
+    }
+
+    // -------------------------------------------------------------------------
+    // Key helpers
+    // -------------------------------------------------------------------------
+
+    private prefixKey(key: string): string {
+        return `${this.prefix}${key}`;
+    }
+
+    private tagIndexKey(tag: string): string {
+        return `${this.prefix}${TAG_INDEX_PREFIX}${tag}`;
+    }
+
+    // -------------------------------------------------------------------------
+    // Core API
+    // -------------------------------------------------------------------------
+
+    /**
+     * Retrieve a cached value by key.
+     * Returns `undefined` when the key is absent or has expired.
+     */
+    async get<T = unknown>(key: string): Promise<T | undefined> {
+        const raw = await this.adapter.get(this.prefixKey(key));
+        if (raw === undefined || raw === null) return undefined;
+
+        const text = raw as string;
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(text);
+        } catch {
+            throw new Error(
+                `cache-kit: failed to deserialize value for key "${key}". ` +
+                'The stored value is not valid JSON.'
+            );
+        }
+
+        assertNoPollution(text, parsed);
+        return parsed as T;
+    }
+
+    /**
+     * Store a value under key, optionally with a TTL and/or tags.
+     *
+     * @param key     Cache key (namespace prefix is applied automatically).
+     * @param value   Any JSON-serialisable value.
+     * @param options `ttl` in seconds and/or `tags` for group invalidation.
+     *                A bare number is treated as `ttl` seconds (shorthand).
+     */
+    async set<T>(key: string, value: T, options?: number | SetOptions): Promise<void> {
+        const { ttl, tags } = this.resolveSetOptions(options);
+        const serialized = JSON.stringify(value);
+        const effectiveTtl = ttl ?? this.defaultTtl;
+
+        await this.adapter.set(this.prefixKey(key), serialized, effectiveTtl);
+
+        if (tags && tags.length > 0) {
+            await this.indexTags(key, tags);
+        }
+    }
+
+    /**
+     * Check whether a key exists in the cache (and has not expired).
+     */
+    async has(key: string): Promise<boolean> {
+        return this.adapter.has(this.prefixKey(key));
+    }
+
+    /**
+     * Delete a single key from the cache.
+     */
+    async delete(key: string): Promise<void> {
+        await this.adapter.del(this.prefixKey(key));
+    }
+
+    /**
+     * Flush the **entire** backing store shared by this Cache and every other
+     * Cache built on the same adapter.
+     *
+     * Implementation note: the {@link KVAdapter} interface does not expose key
+     * enumeration, so this recycles the adapter via `disconnect()`/`connect()`,
+     * which is a whole-store reset rather than a namespace-scoped one. To avoid
+     * a namespaced sub-cache silently nuking its siblings, this method refuses
+     * to run when a namespace prefix is set: it is only valid on a root Cache.
+     *
+     * @throws Error when called on a namespaced Cache (a prefix is set).
+     */
+    async clear(): Promise<void> {
+        if (this.prefix !== '') {
+            const namespace = this.prefix.replace(/:$/, '');
+            throw new Error(
+                `cache-kit: clear() resets the entire shared backing store and ` +
+                `cannot be called on the namespaced cache "${namespace}". ` +
+                'Delete individual keys with delete(), invalidate a group with ' +
+                'invalidateTag(), or call clear() on the root cache to reset everything.'
+            );
+        }
+        await this.adapter.disconnect();
+        await this.adapter.connect();
+    }
+
+    // -------------------------------------------------------------------------
+    // Cache-aside (remember / wrap)
+    // -------------------------------------------------------------------------
+
+    /**
+     * Return the cached value for `key` if present; otherwise call `fallback`,
+     * store the result with the given TTL, and return it.
+     *
+     * The fallback is called **exactly once** on a cache miss — never on a hit.
+     *
+     * @param key      Cache key.
+     * @param ttl      TTL in seconds for the stored value.
+     * @param fallback Async factory invoked on a cache miss.
+     */
+    async remember<T>(key: string, ttl: number, fallback: () => Promise<T>): Promise<T> {
+        const cached = await this.get<T>(key);
+        if (cached !== undefined) return cached;
+
+        let value: T;
+        try {
+            value = await fallback();
+        } catch (error) {
+            throw new Error(
+                `cache-kit: remember() fallback for key "${key}" threw: ${String(error)}`
+            );
+        }
+
+        await this.set(key, value, { ttl });
+        return value;
+    }
+
+    /** Alias for {@link remember}. */
+    readonly wrap = this.remember.bind(this);
+
+    // -------------------------------------------------------------------------
+    // Tag-based invalidation
+    // -------------------------------------------------------------------------
+
+    /**
+     * Invalidate every cached entry that was stored with the given tag.
+     *
+     * After this call all keys associated with `tag` are deleted and the tag
+     * index entry is removed. Entries carrying other tags are unaffected.
+     */
+    async invalidateTag(tag: string): Promise<void> {
+        const indexKey = this.tagIndexKey(tag);
+        const raw = await this.adapter.get(indexKey);
+        if (raw === null || raw === undefined) return;
+
+        let keys: string[];
+        try {
+            keys = JSON.parse(raw as string) as string[];
+        } catch {
+            keys = [];
+        }
+
+        await Promise.all([
+            ...keys.map((k) => this.adapter.del(this.prefixKey(k))),
+            this.adapter.del(indexKey),
+        ]);
+    }
+
+    // -------------------------------------------------------------------------
+    // Namespace helper
+    // -------------------------------------------------------------------------
+
+    /**
+     * Return a new `Cache` sharing the same backing adapter but with an
+     * additional namespace prefix, preventing key collisions between modules.
+     *
+     * @example
+     * ```ts
+     * const users = cache.namespace('users');
+     * const posts = cache.namespace('posts');
+     * // 'users:profile:1' and 'posts:profile:1' are distinct keys
+     * ```
+     */
+    namespace(prefix: string): Cache {
+        const parentNs = this.prefix.replace(/:$/, '');
+        const combinedPrefix = parentNs ? `${parentNs}:${prefix}` : prefix;
+        return new Cache(this.adapter, {
+            namespace: combinedPrefix,
+            defaultTtl: this.defaultTtl,
+        });
+    }
+
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+
+    private resolveSetOptions(options?: number | SetOptions): SetOptions {
+        if (options === undefined) return {};
+        if (typeof options === 'number') return { ttl: options };
+        return options;
+    }
+
+    private async indexTags(key: string, tags: string[]): Promise<void> {
+        await Promise.all(
+            tags.map(async (tag) => {
+                const indexKey = this.tagIndexKey(tag);
+                const raw = await this.adapter.get(indexKey);
+                let keys: string[] = [];
+                if (raw !== null && raw !== undefined) {
+                    try {
+                        keys = JSON.parse(raw as string) as string[];
+                    } catch {
+                        keys = [];
+                    }
+                }
+                const updated = keys.includes(key) ? keys : [...keys, key];
+                await this.adapter.set(indexKey, JSON.stringify(updated));
+            })
+        );
+    }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { Cache } from './cache';
+export type { CacheOptions, SetOptions } from './types';

package/src/memory-adapter.ts

@@ -0,0 +1,58 @@
+import type { KVAdapter } from './types';
+
+/**
+ * Lightweight in-memory {@link KVAdapter} used as the default backing store
+ * when no adapter is supplied to the {@link Cache} constructor.
+ *
+ * This is intentionally a thin Map wrapper — it mirrors kv-kit's MemoryAdapter
+ * without depending on an unexported internal symbol.
+ */
+export class MemoryAdapter implements KVAdapter {
+    readonly id = 'memory';
+    private store = new Map<string, unknown>();
+    private timers = new Map<string, ReturnType<typeof setTimeout>>();
+
+    connect(): void {
+        // no-op
+    }
+
+    disconnect(): void {
+        for (const timer of this.timers.values()) clearTimeout(timer);
+        this.timers = new Map();
+        this.store = new Map();
+    }
+
+    async get<T = unknown>(key: string): Promise<T | undefined> {
+        return this.store.get(key) as T | undefined;
+    }
+
+    async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {
+        this.clearTimer(key);
+        this.store.set(key, value);
+        if (ttl) {
+            const timer = setTimeout(() => {
+                this.store.delete(key);
+                this.timers.delete(key);
+            }, ttl * 1000);
+            timer.unref?.();
+            this.timers.set(key, timer);
+        }
+    }
+
+    async del(key: string): Promise<void> {
+        this.clearTimer(key);
+        this.store.delete(key);
+    }
+
+    private clearTimer(key: string): void {
+        const existing = this.timers.get(key);
+        if (existing) {
+            clearTimeout(existing);
+            this.timers.delete(key);
+        }
+    }
+
+    async has(key: string): Promise<boolean> {
+        return this.store.has(key);
+    }
+}

package/src/types.ts

@@ -0,0 +1,22 @@
+import type { KVAdapter } from '@iskra-bun/kv-kit';
+
+export type { KVAdapter };
+
+export interface CacheOptions {
+    /** Prefix prepended to every key — prevents collisions between modules. */
+    namespace?: string;
+    /** Default TTL in seconds applied when set() is called without an explicit ttl. */
+    defaultTtl?: number;
+}
+
+export interface SetOptions {
+    /** TTL in seconds. Overrides any defaultTtl configured on the Cache. */
+    ttl?: number;
+    /**
+     * Tag names associated with this entry.
+     *
+     * Pass one or more tags so the entry can later be invalidated as a group
+     * via `Cache.invalidateTag(tag)`.
+     */
+    tags?: string[];
+}