@iskra-bun/cache-kit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @iskra-bun/cache-kit
 
+## 0.2.0
+
+### Minor Changes
+
+- 938dd41: **Security** fixes from the data-kits audit (round 2).
+
+    - `storage-kit` (**breaking**): files are stored and served with a type from their extension (`contentTypeFor`), and anything but a raster image as a download. The S3 adapter stores a `Content-Disposition` with each object (`attachment` unless it is a PNG, JPEG, GIF, WebP, AVIF, BMP or ICO image; `put(..., { contentDisposition })` to choose), and `url()` signs `response-content-type` and `response-content-disposition` into presigned URLs whatever the object was stored with (`url(path, expiresIn, { contentType, contentDisposition })` to choose): an upload named `logo.svg` or `invoice.html` was stored as `image/svg+xml`/`text/html` and ran its scripts on the bucket's origin. HTML, SVG, XML and JavaScript are now `application/octet-stream`. `put(..., { overwrite: false })` throws the new `FileExistsError` instead of replacing a stored file (S3 `If-None-Match: *`, an exclusive create locally); `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner` now need 3.635 or later, the first releases that send `If-None-Match` on a put (earlier ones dropped it, and the file was replaced). The plaintext-endpoint guard parses the endpoint as a URL, as the SDK does: `http:/minio:9000`, `http:minio:9000` and `http:\\minio:9000` were accepted without `useSSL: false`; an endpoint that is not an `http(s)` URL is rejected.
+    - `web-kit` uploads (**breaking**): the upload route stores a file with the type of its extension, never `File.type` (which Bun derives from the name), and `uploadFromRequest()` too. Downloads are streamed with `getStream()` (each one was buffered twice), typed by extension, `attachment` unless a raster image, and sandboxed (`Content-Security-Policy: sandbox`). Without `allowedExtensions`, active web content (`.html`, `.svg`, `.xml`, `.js`...) is refused (400) unless listed. `authorize(c, action, target)` receives what the action touches (`{ key, subfolder, filename, size, type }`), and `upload` is asked again with it before the file is written. An upload no longer replaces a stored file: **409** unless `overwrite: true`.
+    - `mailer-kit` (**breaking**): every `to`, `cc`, `bcc` and `replyTo` entry must be one bare address, or a new `{ name, address }` object for a display name, in every adapter (the mock too); only `from` was checked. One value such as `"bob@example.com <attacker@evil.test>, x@example.com"`, a group (`"undisclosed: a@evil.test; b@x.com"`, `"a@evil.test:b@x.com"`) or `{ address: "bob@example.com\r\nBcc: …" }` mailed other recipients than the ones an allowlist checked. Addresses may not contain whitespace, control characters or `<>()[]\,;:"` and need exactly one `@`; `replyTo` takes one recipient. `checkRecipients()` is exported. Mailgun cuts the `subject` at a CR/LF, as it does header values.
+    - `web-kit` email: `EmailFeature`'s adapter checks recipients with mailer-kit's rules (object recipients were tested as `"[object Object]"`), and rejects through the returned promise instead of throwing synchronously.
+    - `kv-kit`: the `KVAdapter` contract gains an optional `clear(prefix?)` and expiring sets (`sadd(key, member, ttl?)`, `sdrain(key)`), implemented by both adapters and `KVManager`. `KVManager.clear()` deletes its namespace's keys; with Redis it uses `SCAN` + `DEL` (within ioredis' `keyPrefix` too) and, without a namespace, refuses to empty the whole database unless `new KVManager({ flushDb: true })`. Expiring sets are sorted sets scored by expiry, updated by one atomic script: cache-kit's tag index. The memory adapter stores and returns copies (`structuredClone`), as Redis does (**breaking** for values that cannot be cloned, such as functions): it returned the stored object itself, so one request's mutation showed up in every other.
+    - `cache-kit` (**breaking**): `clear()` runs the adapter's `clear()` with the cache's namespace instead of `disconnect()`/`connect()` of the shared adapter, which on Redis deleted nothing (cached permissions stayed), failed concurrent operations meanwhile, and left the adapter dead when the reconnect failed during a Redis blip. A namespaced cache now clears its own entries (it used to throw); an adapter without `clear()` makes it throw. The tag index is kv-kit's expiring set when the adapter has one (one atomic `sadd` per tagged `set()`; each one read and rewrote the whole index, and the last 10k of 40k tagged sets took 30 s), and otherwise a JSON list that drops expired keys, expires with its last entry and keeps at most 10,000 (the oldest are deleted with their data); indexes written before are still drained by `invalidateTag()`. A value with a `__proto__`/`constructor`/`prototype` key is a miss (deleted when read; not stored by `set()`), so `remember()` refetches instead of every read throwing until the TTL ran out. Data keys and namespaces containing `__cache_tag__:`/`__cache_tags__:` (at the start or after a `:`) are rejected: a caller-chosen key could rewrite a tag index, and `invalidateTag()` deleted whatever it listed.
+    - `db-kit` (**breaking**): `MigrationHelper` and the CLI run only the drizzle-kit installed in the project (`node_modules/.bin` of the working directory or a parent), with `bunx --no-install drizzle-kit`, and fail with a `MigrationError` where it is not installed. drizzle-kit is a devDependency, so in a production install `bunx drizzle-kit` downloaded its latest release from npm and ran it with `DATABASE_URL` in its environment.
+
+### Patch Changes
+
+- 7e89103: Concurrent `set()` calls with the same tag no longer lose keys from the tag index (within a process), so `invalidateTag()` deletes them all. The prototype-pollution guard also catches an escaped `"__proto__"` key. `remember()` rethrows the fallback's own error instead of wrapping it in a plain `Error`. The memory adapter keeps entries whose TTL exceeds `setTimeout`'s limit, and a negative TTL is rejected.
+- 98e05ef: When indexing a tagged entry's tags fails, `set()` deletes the entry it just wrote before rejecting. The entry used to stay cached without being listed under its tags, so `invalidateTag()` never removed it.
+- 840439a: Packages declare the runtime they are tested on: `engines.bun` `>=1.3.0` (the monorepo now builds and tests on Bun 1.3). `create-iskra`, a CLI that also runs under `npm create iskra`, declares `engines.node` `>=18`.
+
+    Every package is published with an npm provenance attestation (`publishConfig.provenance`), linking each version to the commit and CI run that built it.
+
+- Updated dependencies [620da18]
+- Updated dependencies [b635a2c]
+- Updated dependencies [5b2b0fd]
+- Updated dependencies [58d4a8f]
+- Updated dependencies [5c70c5b]
+- Updated dependencies [ec198d4]
+- Updated dependencies [cb3ec43]
+- Updated dependencies [ef2009b]
+- Updated dependencies [840439a]
+- Updated dependencies [cb3ec43]
+- Updated dependencies [620da18]
+- Updated dependencies [87f6de2]
+- Updated dependencies [58d4a8f]
+- Updated dependencies [dbf8817]
+- Updated dependencies [c4ff1e3]
+- Updated dependencies [7e89103]
+- Updated dependencies [3dc5581]
+- Updated dependencies [9872d30]
+- Updated dependencies [9bb254d]
+- Updated dependencies [f2346f5]
+- Updated dependencies [938dd41]
+- Updated dependencies [3579944]
+    - @iskra-bun/core@0.2.0
+    - @iskra-bun/kv-kit@0.3.0
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -44,7 +44,7 @@ await cache.invalidateTag('items'); // elimina item:1 e item:2
 
 ## Documentacion
 
-Guia completa: [docs/cache-kit.md](../../docs/cache-kit.md)
+Guia completa: [@iskra-bun/cache-kit](https://iskra-docs.fly.dev/es/packages/cache-kit/)
 
 ## Licencia
 

package/dist/index.d.ts

@@ -48,10 +48,12 @@ declare class Cache {
     private readonly defaultTtl;
     constructor(adapter?: KVAdapter, options?: CacheOptions);
     private prefixKey;
-    private tagIndexKey;
+    private tagSetKey;
+    private tagListKey;
     /**
      * Retrieve a cached value by key.
-     * Returns `undefined` when the key is absent or has expired.
+     * Returns `undefined` when the key is absent or has expired, or when the
+     * stored value carries a prototype-pollution key (the entry is deleted).
      */
     get<T = unknown>(key: string): Promise<T | undefined>;
     /**
@@ -72,16 +74,16 @@ declare class Cache {
      */
     delete(key: string): Promise<void>;
     /**
-     * Flush the **entire** backing store shared by this Cache and every other
-     * Cache built on the same adapter.
+     * Delete every entry of this cache: its namespace (with the namespaces and
+     * tag indexes under it), or all the adapter's keys for a root cache. It
+     * runs the adapter's `clear()`: a KVManager clears its own namespace, and
+     * on Redis never the whole database unless `flushDb` allows it.
      *
-     * 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.
+     * It used to recycle the adapter (disconnect + connect): on Redis that
+     * deleted nothing, and a reconnect failing during a blip left the shared
+     * adapter dead after Redis recovered.
      *
-     * @throws Error when called on a namespaced Cache (a prefix is set).
+     * @throws Error when the adapter has no `clear()`.
      */
     clear(): Promise<void>;
     /**
@@ -89,6 +91,8 @@ declare class Cache {
      * store the result with the given TTL, and return it.
      *
      * The fallback is called **exactly once** on a cache miss — never on a hit.
+     * An error it throws is rethrown as is (so its class, status or code still
+     * reach the caller's error handling) and nothing is cached.
      *
      * @param key      Cache key.
      * @param ttl      TTL in seconds for the stored value.
@@ -104,6 +108,9 @@ declare class Cache {
      * index entry is removed. Entries carrying other tags are unaffected.
      */
     invalidateTag(tag: string): Promise<void>;
+    private drainList;
+    /** Deletes the entries of `keys` (relative to this cache), in batches; never a tag index. */
+    private deleteKeys;
     /**
      * Return a new `Cache` sharing the same backing adapter but with an
      * additional namespace prefix, preventing key collisions between modules.
@@ -117,7 +124,22 @@ declare class Cache {
      */
     namespace(prefix: string): Cache;
     private resolveSetOptions;
+    /**
+     * Adds `key` to each tag's index, for as long as the entry lives. With an
+     * adapter that has `sadd` it is one atomic step per tag, whatever the size
+     * of the index. Otherwise a JSON list is rewritten, one set() at a time per
+     * index key (concurrent set() calls used to both read the old index and
+     * one key was lost); that lock is per-process, so instances sharing a store
+     * can still race (see the docs).
+     */
     private indexTags;
+    /**
+     * Rewriting the whole list on every set() made each one slower than the
+     * last, and expired keys were never dropped: they are now, the list expires
+     * with its last entry, and past MAX_TAG_LIST the oldest entries are deleted
+     * with their data (a deleted entry needs no invalidating).
+     */
+    private addToList;
 }
 
 export { Cache, type CacheOptions, type SetOptions };

package/dist/index.js

@@ -1,7 +1,9 @@
 // src/memory-adapter.ts
+var MAX_TIMEOUT_MS = 2 ** 31 - 1;
 var MemoryAdapter = class {
   id = "memory";
   store = /* @__PURE__ */ new Map();
+  sets = /* @__PURE__ */ new Map();
   timers = /* @__PURE__ */ new Map();
   connect() {
   }
@@ -9,25 +11,36 @@ var MemoryAdapter = class {
     for (const timer of this.timers.values()) clearTimeout(timer);
     this.timers = /* @__PURE__ */ new Map();
     this.store = /* @__PURE__ */ new Map();
+    this.sets = /* @__PURE__ */ new Map();
   }
   async get(key) {
     return this.store.get(key);
   }
   async set(key, value, ttl) {
     this.clearTimer(key);
+    this.sets.delete(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);
-    }
+    if (ttl && ttl > 0 && Number.isFinite(ttl)) this.expireIn(key, ttl * 1e3);
+  }
+  /** Arms the expiry timer, in steps when the delay exceeds setTimeout's limit. */
+  expireIn(key, ms) {
+    const step = Math.min(ms, MAX_TIMEOUT_MS);
+    const timer = setTimeout(() => {
+      if (ms > step) {
+        this.expireIn(key, ms - step);
+        return;
+      }
+      this.store.delete(key);
+      this.sets.delete(key);
+      this.timers.delete(key);
+    }, step);
+    timer.unref?.();
+    this.timers.set(key, timer);
   }
   async del(key) {
     this.clearTimer(key);
     this.store.delete(key);
+    this.sets.delete(key);
   }
   clearTimer(key) {
     const existing = this.timers.get(key);
@@ -37,30 +50,104 @@ var MemoryAdapter = class {
     }
   }
   async has(key) {
-    return this.store.has(key);
+    return this.store.has(key) || this.sets.has(key);
+  }
+  async clear(prefix = "") {
+    for (const key of [...this.store.keys(), ...this.sets.keys()]) {
+      if (key.startsWith(prefix)) await this.del(key);
+    }
+  }
+  async sadd(key, member, ttl) {
+    const now = Date.now();
+    const expiresAt = ttl && ttl > 0 && Number.isFinite(ttl) ? now + ttl * 1e3 : Infinity;
+    let set = this.sets.get(key);
+    if (!set) {
+      this.store.delete(key);
+      set = { members: /* @__PURE__ */ new Map(), expiresAt: 0, pruneAt: 64 };
+      this.sets.set(key, set);
+    }
+    set.members.set(member, Math.max(set.members.get(member) ?? 0, expiresAt));
+    if (set.members.size >= set.pruneAt) {
+      for (const [name, at] of set.members) if (at <= now) set.members.delete(name);
+      set.pruneAt = Math.max(64, set.members.size * 2);
+    }
+    if (expiresAt > set.expiresAt) {
+      set.expiresAt = expiresAt;
+      this.clearTimer(key);
+      if (expiresAt !== Infinity) this.expireIn(key, expiresAt - now);
+    }
+  }
+  async sdrain(key) {
+    const set = this.sets.get(key);
+    if (!set) return [];
+    this.sets.delete(key);
+    this.clearTimer(key);
+    const now = Date.now();
+    return [...set.members].filter(([, at]) => at > now).map(([name]) => name);
   }
 };
 
 // src/cache.ts
-var TAG_INDEX_PREFIX = "__cache_tag__:";
+var TAG_SET_PREFIX = "__cache_tags__:";
+var TAG_LIST_PREFIX = "__cache_tag__:";
+var RESERVED = /(?:^|:)__cache_tags?__:/;
+var MAX_TAG_LIST = 1e4;
+var DELETE_BATCH = 1e3;
 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).`
-        );
-      }
+var DANGEROUS_KEY_TEXT = /"(?:__proto__|constructor|prototype)":/;
+var PollutionError = class extends Error {
+};
+var indexLocks = /* @__PURE__ */ new WeakMap();
+function withLock(adapter, key, fn) {
+  let locks = indexLocks.get(adapter);
+  if (!locks) indexLocks.set(adapter, locks = /* @__PURE__ */ new Map());
+  const previous = locks.get(key) ?? Promise.resolve();
+  const result = previous.then(fn, fn);
+  const settled = result.then(
+    () => void 0,
+    () => void 0
+  );
+  locks.set(key, settled);
+  void settled.then(() => {
+    if (locks.get(key) === settled) locks.delete(key);
+  });
+  return result;
+}
+function parseSafely(raw) {
+  return JSON.parse(raw, function(key, value) {
+    if (DANGEROUS_KEYS.includes(key)) {
+      throw new PollutionError(
+        `cache-kit: refusing to deserialize value containing the unsafe key "${key}" (prototype-pollution risk).`
+      );
     }
+    return value;
+  });
+}
+function isPolluted(serialized) {
+  if (serialized === void 0 || !DANGEROUS_KEY_TEXT.test(serialized)) return false;
+  try {
+    parseSafely(serialized);
+    return false;
+  } catch (error) {
+    return error instanceof PollutionError;
   }
 }
-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)
-  );
+function parseTagList(raw) {
+  if (typeof raw !== "string") return [];
+  let list;
+  try {
+    list = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(list)) return [];
+  return list.flatMap((entry) => {
+    if (typeof entry === "string") return [[entry, 0]];
+    if (Array.isArray(entry) && typeof entry[0] === "string" && typeof entry[1] === "number") {
+      return [[entry[0], entry[1]]];
+    }
+    return [];
+  });
 }
 var Cache = class _Cache {
   adapter;
@@ -70,37 +157,47 @@ var Cache = class _Cache {
     this.adapter = adapter ?? new MemoryAdapter();
     this.prefix = options.namespace ? `${options.namespace}:` : "";
     this.defaultTtl = options.defaultTtl;
+    if (RESERVED.test(this.prefix)) {
+      throw new Error(`cache-kit: the namespace "${options.namespace}" is reserved for tag indexes`);
+    }
   }
   // -------------------------------------------------------------------------
   // Key helpers
   // -------------------------------------------------------------------------
   prefixKey(key) {
-    return `${this.prefix}${key}`;
+    const full = `${this.prefix}${key}`;
+    if (RESERVED.test(full)) throw new Error(`cache-kit: the key "${key}" is reserved for tag indexes`);
+    return full;
   }
-  tagIndexKey(tag) {
-    return `${this.prefix}${TAG_INDEX_PREFIX}${tag}`;
+  tagSetKey(tag) {
+    return `${this.prefix}${TAG_SET_PREFIX}${tag}`;
+  }
+  tagListKey(tag) {
+    return `${this.prefix}${TAG_LIST_PREFIX}${tag}`;
   }
   // -------------------------------------------------------------------------
   // Core API
   // -------------------------------------------------------------------------
   /**
    * Retrieve a cached value by key.
-   * Returns `undefined` when the key is absent or has expired.
+   * Returns `undefined` when the key is absent or has expired, or when the
+   * stored value carries a prototype-pollution key (the entry is deleted).
    */
   async get(key) {
-    const raw = await this.adapter.get(this.prefixKey(key));
+    const dataKey = this.prefixKey(key);
+    const raw = await this.adapter.get(dataKey);
     if (raw === void 0 || raw === null) return void 0;
-    const text = raw;
-    let parsed;
     try {
-      parsed = JSON.parse(text);
-    } catch {
+      return parseSafely(raw);
+    } catch (error) {
+      if (error instanceof PollutionError) {
+        await this.adapter.del(dataKey);
+        return void 0;
+      }
       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.
@@ -112,11 +209,27 @@ var Cache = class _Cache {
    */
   async set(key, value, options) {
     const { ttl, tags } = this.resolveSetOptions(options);
+    const dataKey = this.prefixKey(key);
     const serialized = JSON.stringify(value);
     const effectiveTtl = ttl ?? this.defaultTtl;
-    await this.adapter.set(this.prefixKey(key), serialized, effectiveTtl);
+    if (effectiveTtl !== void 0 && effectiveTtl !== 0 && !(effectiveTtl > 0 && Number.isFinite(effectiveTtl))) {
+      throw new RangeError(
+        `cache-kit: invalid TTL ${String(effectiveTtl)}: expected a positive number of seconds`
+      );
+    }
+    if (isPolluted(serialized)) {
+      await this.adapter.del(dataKey);
+      return;
+    }
+    await this.adapter.set(dataKey, serialized, effectiveTtl);
     if (tags && tags.length > 0) {
-      await this.indexTags(key, tags);
+      try {
+        await this.indexTags(key, tags, effectiveTtl);
+      } catch (err) {
+        await this.adapter.del(dataKey).catch(() => {
+        });
+        throw err;
+      }
     }
   }
   /**
@@ -132,26 +245,22 @@ var Cache = class _Cache {
     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.
+   * Delete every entry of this cache: its namespace (with the namespaces and
+   * tag indexes under it), or all the adapter's keys for a root cache. It
+   * runs the adapter's `clear()`: a KVManager clears its own namespace, and
+   * on Redis never the whole database unless `flushDb` allows it.
    *
-   * 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.
+   * It used to recycle the adapter (disconnect + connect): on Redis that
+   * deleted nothing, and a reconnect failing during a blip left the shared
+   * adapter dead after Redis recovered.
    *
-   * @throws Error when called on a namespaced Cache (a prefix is set).
+   * @throws Error when the adapter has no `clear()`.
    */
   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.`
-      );
+    if (!this.adapter.clear) {
+      throw new Error(`cache-kit: the "${this.adapter.id}" adapter cannot clear its keys (it has no clear())`);
     }
-    await this.adapter.disconnect();
-    await this.adapter.connect();
+    await this.adapter.clear(this.prefix);
   }
   // -------------------------------------------------------------------------
   // Cache-aside (remember / wrap)
@@ -161,6 +270,8 @@ var Cache = class _Cache {
    * store the result with the given TTL, and return it.
    *
    * The fallback is called **exactly once** on a cache miss — never on a hit.
+   * An error it throws is rethrown as is (so its class, status or code still
+   * reach the caller's error handling) and nothing is cached.
    *
    * @param key      Cache key.
    * @param ttl      TTL in seconds for the stored value.
@@ -169,14 +280,7 @@ var Cache = class _Cache {
   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)}`
-      );
-    }
+    const value = await fallback();
     await this.set(key, value, { ttl });
     return value;
   }
@@ -192,19 +296,27 @@ var Cache = class _Cache {
    * 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 = [];
+    const listKey = this.tagListKey(tag);
+    await withLock(this.adapter, listKey, async () => {
+      const keys = await this.drainList(listKey);
+      if (this.adapter.sdrain) keys.push(...await this.adapter.sdrain(this.tagSetKey(tag)));
+      await this.deleteKeys(keys);
+    });
+  }
+  async drainList(listKey) {
+    const raw = await this.adapter.get(listKey);
+    if (raw === null || raw === void 0) return [];
+    await this.adapter.del(listKey);
+    return parseTagList(raw).map(([key]) => key);
+  }
+  /** Deletes the entries of `keys` (relative to this cache), in batches; never a tag index. */
+  async deleteKeys(keys) {
+    const full = [...new Set(keys)].map((key) => `${this.prefix}${key}`).filter((key) => !RESERVED.test(key));
+    for (let i = 0; i < full.length; i += DELETE_BATCH) {
+      const batch = full.slice(i, i + DELETE_BATCH);
+      if (this.adapter.mdel) await this.adapter.mdel(batch);
+      else await Promise.all(batch.map((key) => this.adapter.del(key)));
     }
-    await Promise.all([
-      ...keys.map((k) => this.adapter.del(this.prefixKey(k))),
-      this.adapter.del(indexKey)
-    ]);
   }
   // -------------------------------------------------------------------------
   // Namespace helper
@@ -236,24 +348,44 @@ var Cache = class _Cache {
     if (typeof options === "number") return { ttl: options };
     return options;
   }
-  async indexTags(key, tags) {
+  /**
+   * Adds `key` to each tag's index, for as long as the entry lives. With an
+   * adapter that has `sadd` it is one atomic step per tag, whatever the size
+   * of the index. Otherwise a JSON list is rewritten, one set() at a time per
+   * index key (concurrent set() calls used to both read the old index and
+   * one key was lost); that lock is per-process, so instances sharing a store
+   * can still race (see the docs).
+   */
+  async indexTags(key, tags, ttl) {
+    const adapter = this.adapter;
     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));
+      tags.map((tag) => {
+        if (adapter.sadd && adapter.sdrain) return adapter.sadd(this.tagSetKey(tag), key, ttl || void 0);
+        const listKey = this.tagListKey(tag);
+        return withLock(adapter, listKey, () => this.addToList(listKey, key, ttl));
       })
     );
   }
+  /**
+   * Rewriting the whole list on every set() made each one slower than the
+   * last, and expired keys were never dropped: they are now, the list expires
+   * with its last entry, and past MAX_TAG_LIST the oldest entries are deleted
+   * with their data (a deleted entry needs no invalidating).
+   */
+  async addToList(listKey, key, ttl) {
+    const now = Date.now();
+    const expiresAt = ttl ? now + ttl * 1e3 : 0;
+    const entries = parseTagList(await this.adapter.get(listKey)).filter(([, at]) => at === 0 || at > now);
+    const existing = entries.find(([listed]) => listed === key);
+    if (!existing) entries.push([key, expiresAt]);
+    else if (existing[1] !== 0) existing[1] = expiresAt === 0 ? 0 : Math.max(existing[1], expiresAt);
+    const evicted = entries.length > MAX_TAG_LIST ? entries.splice(0, entries.length - MAX_TAG_LIST) : [];
+    await this.deleteKeys(evicted.map(([listed]) => listed));
+    const forever = entries.some(([, at]) => at === 0);
+    const last = entries.reduce((max, [, at]) => Math.max(max, at), 0);
+    const listTtl = forever ? void 0 : (last - now) / 1e3;
+    await this.adapter.set(listKey, JSON.stringify(entries), listTtl);
+  }
 };
 export {
   Cache

package/dist/index.js.map

@@ -1 +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":[]}
+{"version":3,"sources":["../src/memory-adapter.ts","../src/cache.ts"],"sourcesContent":["import type { KVAdapter } from './types';\n\n/** setTimeout's limit: a longer delay (a TTL over ~24.8 days) fires at once. */\nconst MAX_TIMEOUT_MS = 2 ** 31 - 1;\n\n/** An expiring set: each member's expiry (ms since the epoch, Infinity for none). */\ninterface ExpiringSet {\n    members: Map<string, number>;\n    expiresAt: number;\n    /** Size at which expired members are next dropped. */\n    pruneAt: number;\n}\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 sets = new Map<string, ExpiringSet>();\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        this.sets = 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.sets.delete(key);\n        this.store.set(key, value);\n        if (ttl && ttl > 0 && Number.isFinite(ttl)) this.expireIn(key, ttl * 1000);\n    }\n\n    /** Arms the expiry timer, in steps when the delay exceeds setTimeout's limit. */\n    private expireIn(key: string, ms: number): void {\n        const step = Math.min(ms, MAX_TIMEOUT_MS);\n        const timer = setTimeout(() => {\n            if (ms > step) {\n                this.expireIn(key, ms - step);\n                return;\n            }\n            this.store.delete(key);\n            this.sets.delete(key);\n            this.timers.delete(key);\n        }, step);\n        timer.unref?.();\n        this.timers.set(key, timer);\n    }\n\n    async del(key: string): Promise<void> {\n        this.clearTimer(key);\n        this.store.delete(key);\n        this.sets.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) || this.sets.has(key);\n    }\n\n    async clear(prefix = ''): Promise<void> {\n        for (const key of [...this.store.keys(), ...this.sets.keys()]) {\n            if (key.startsWith(prefix)) await this.del(key);\n        }\n    }\n\n    async sadd(key: string, member: string, ttl?: number): Promise<void> {\n        const now = Date.now();\n        const expiresAt = ttl && ttl > 0 && Number.isFinite(ttl) ? now + ttl * 1000 : Infinity;\n        let set = this.sets.get(key);\n        if (!set) {\n            this.store.delete(key);\n            set = { members: new Map(), expiresAt: 0, pruneAt: 64 };\n            this.sets.set(key, set);\n        }\n        // A member keeps its latest expiry, and expired members go each time\n        // the set doubles (O(1) per add on average), as in kv-kit.\n        set.members.set(member, Math.max(set.members.get(member) ?? 0, expiresAt));\n        if (set.members.size >= set.pruneAt) {\n            for (const [name, at] of set.members) if (at <= now) set.members.delete(name);\n            set.pruneAt = Math.max(64, set.members.size * 2);\n        }\n        if (expiresAt > set.expiresAt) {\n            set.expiresAt = expiresAt;\n            this.clearTimer(key);\n            if (expiresAt !== Infinity) this.expireIn(key, expiresAt - now);\n        }\n    }\n\n    async sdrain(key: string): Promise<string[]> {\n        const set = this.sets.get(key);\n        if (!set) return [];\n        this.sets.delete(key);\n        this.clearTimer(key);\n        const now = Date.now();\n        return [...set.members].filter(([, at]) => at > now).map(([name]) => name);\n    }\n}\n","import { MemoryAdapter } from './memory-adapter';\nimport type { KVAdapter, CacheOptions, SetOptions } from './types';\n\n/** A tag's index as an expiring set, with adapters that have `sadd`/`sdrain`. */\nconst TAG_SET_PREFIX = '__cache_tags__:';\n\n/** A tag's index as a JSON list: with other adapters, and every index written before 0.x. */\nconst TAG_LIST_PREFIX = '__cache_tag__:';\n\n/**\n * Data keys and namespaces may not reach the tag indexes: a key such as\n * `__cache_tag__:perms` overwrote the index, and invalidateTag('perms') then\n * deleted whatever keys it listed.\n */\nconst RESERVED = /(?:^|:)__cache_tags?__:/;\n\n/** Longest JSON tag index: beyond it, the oldest entries are deleted along with their data. */\nconst MAX_TAG_LIST = 10_000;\n\n/** Keys deleted per call when a tag is invalidated. */\nconst DELETE_BATCH = 1000;\n\n/** Keys that enable prototype-pollution when an object is later deep-merged. */\nconst DANGEROUS_KEYS = ['__proto__', 'constructor', 'prototype'] as const;\n\n/** One of them as a key in JSON.stringify's output, which escapes none of their characters. */\nconst DANGEROUS_KEY_TEXT = /\"(?:__proto__|constructor|prototype)\":/;\n\nclass PollutionError extends Error {}\n\n/** A JSON tag index entry: the key and its expiry (ms since the epoch, 0 for none). */\ntype TagEntry = [key: string, expiresAt: number];\n\n/** Pending tag-index updates per adapter (shared by its namespaced caches) and key. */\nconst indexLocks = new WeakMap<object, Map<string, Promise<unknown>>>();\n\n/** Runs `fn` after the previous `fn` for the same adapter and key has settled. */\nfunction withLock<T>(adapter: object, key: string, fn: () => Promise<T>): Promise<T> {\n    let locks = indexLocks.get(adapter);\n    if (!locks) indexLocks.set(adapter, (locks = new Map()));\n    const previous = locks.get(key) ?? Promise.resolve();\n    const result = previous.then(fn, fn);\n    const settled = result.then(\n        () => undefined,\n        () => undefined,\n    );\n    locks.set(key, settled);\n    void settled.then(() => {\n        if (locks.get(key) === settled) locks.delete(key);\n    });\n    return result;\n}\n\n/**\n * Parses cached JSON, throwing if any object in it carries a\n * prototype-pollution key. Cached payloads can originate from untrusted\n * writers; rejecting these keys at the parse boundary stops a malicious value\n * from reaching code that deep-merges it. The reviver sees every key as\n * parsed, so an escaped spelling such as `\"\\u005f_proto__\"` is caught too\n * (a check of the raw text for `\"__proto__\"` missed it).\n */\nfunction parseSafely(raw: string): unknown {\n    return JSON.parse(raw, function (key, value) {\n        if ((DANGEROUS_KEYS as readonly string[]).includes(key)) {\n            throw new PollutionError(\n                `cache-kit: refusing to deserialize value containing the ` +\n                    `unsafe key \"${key}\" (prototype-pollution risk).`,\n            );\n        }\n        return value;\n    });\n}\n\n/** Whether get() would refuse this serialized value (see parseSafely). */\nfunction isPolluted(serialized: string | undefined): boolean {\n    if (serialized === undefined || !DANGEROUS_KEY_TEXT.test(serialized)) return false;\n    try {\n        parseSafely(serialized);\n        return false;\n    } catch (error) {\n        return error instanceof PollutionError;\n    }\n}\n\n/** A JSON tag index; before 0.x its entries were bare keys, with no expiry. */\nfunction parseTagList(raw: unknown): TagEntry[] {\n    if (typeof raw !== 'string') return [];\n    let list: unknown;\n    try {\n        list = JSON.parse(raw);\n    } catch {\n        return [];\n    }\n    if (!Array.isArray(list)) return [];\n    return list.flatMap((entry): TagEntry[] => {\n        if (typeof entry === 'string') return [[entry, 0]];\n        if (Array.isArray(entry) && typeof entry[0] === 'string' && typeof entry[1] === 'number') {\n            return [[entry[0], entry[1]]];\n        }\n        return [];\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        if (RESERVED.test(this.prefix)) {\n            throw new Error(`cache-kit: the namespace \"${options.namespace}\" is reserved for tag indexes`);\n        }\n    }\n\n    // -------------------------------------------------------------------------\n    // Key helpers\n    // -------------------------------------------------------------------------\n\n    private prefixKey(key: string): string {\n        const full = `${this.prefix}${key}`;\n        if (RESERVED.test(full)) throw new Error(`cache-kit: the key \"${key}\" is reserved for tag indexes`);\n        return full;\n    }\n\n    private tagSetKey(tag: string): string {\n        return `${this.prefix}${TAG_SET_PREFIX}${tag}`;\n    }\n\n    private tagListKey(tag: string): string {\n        return `${this.prefix}${TAG_LIST_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, or when the\n     * stored value carries a prototype-pollution key (the entry is deleted).\n     */\n    async get<T = unknown>(key: string): Promise<T | undefined> {\n        const dataKey = this.prefixKey(key);\n        const raw = await this.adapter.get(dataKey);\n        if (raw === undefined || raw === null) return undefined;\n\n        try {\n            return parseSafely(raw as string) as T;\n        } catch (error) {\n            if (error instanceof PollutionError) {\n                // A miss: thrown, it failed every read until the TTL ran out\n                // (never without one), and remember() did not refetch.\n                await this.adapter.del(dataKey);\n                return undefined;\n            }\n            throw new Error(\n                `cache-kit: failed to deserialize value for key \"${key}\". ` + 'The stored value is not valid JSON.',\n            );\n        }\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 dataKey = this.prefixKey(key);\n        const serialized = JSON.stringify(value);\n        const effectiveTtl = ttl ?? this.defaultTtl;\n        if (effectiveTtl !== undefined && effectiveTtl !== 0 && !(effectiveTtl > 0 && Number.isFinite(effectiveTtl))) {\n            throw new RangeError(\n                `cache-kit: invalid TTL ${String(effectiveTtl)}: expected a positive number of seconds`,\n            );\n        }\n\n        // get() could never return it: nothing is stored (and the old value goes).\n        if (isPolluted(serialized)) {\n            await this.adapter.del(dataKey);\n            return;\n        }\n\n        await this.adapter.set(dataKey, serialized, effectiveTtl);\n\n        if (tags && tags.length > 0) {\n            try {\n                await this.indexTags(key, tags, effectiveTtl);\n            } catch (err) {\n                // An entry its tags do not list would outlive invalidateTag():\n                // drop it and report the failure.\n                await this.adapter.del(dataKey).catch(() => {});\n                throw err;\n            }\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     * Delete every entry of this cache: its namespace (with the namespaces and\n     * tag indexes under it), or all the adapter's keys for a root cache. It\n     * runs the adapter's `clear()`: a KVManager clears its own namespace, and\n     * on Redis never the whole database unless `flushDb` allows it.\n     *\n     * It used to recycle the adapter (disconnect + connect): on Redis that\n     * deleted nothing, and a reconnect failing during a blip left the shared\n     * adapter dead after Redis recovered.\n     *\n     * @throws Error when the adapter has no `clear()`.\n     */\n    async clear(): Promise<void> {\n        if (!this.adapter.clear) {\n            throw new Error(`cache-kit: the \"${this.adapter.id}\" adapter cannot clear its keys (it has no clear())`);\n        }\n        await this.adapter.clear(this.prefix);\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     * An error it throws is rethrown as is (so its class, status or code still\n     * reach the caller's error handling) and nothing is cached.\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        const value = await fallback();\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 listKey = this.tagListKey(tag);\n        await withLock(this.adapter, listKey, async () => {\n            // The JSON list too with an adapter that has sets: entries tagged\n            // before 0.x are listed there.\n            const keys = await this.drainList(listKey);\n            if (this.adapter.sdrain) keys.push(...(await this.adapter.sdrain(this.tagSetKey(tag))));\n            await this.deleteKeys(keys);\n        });\n    }\n\n    private async drainList(listKey: string): Promise<string[]> {\n        const raw = await this.adapter.get(listKey);\n        if (raw === null || raw === undefined) return [];\n        await this.adapter.del(listKey);\n        return parseTagList(raw).map(([key]) => key);\n    }\n\n    /** Deletes the entries of `keys` (relative to this cache), in batches; never a tag index. */\n    private async deleteKeys(keys: string[]): Promise<void> {\n        const full = [...new Set(keys)].map((key) => `${this.prefix}${key}`).filter((key) => !RESERVED.test(key));\n        for (let i = 0; i < full.length; i += DELETE_BATCH) {\n            const batch = full.slice(i, i + DELETE_BATCH);\n            if (this.adapter.mdel) await this.adapter.mdel(batch);\n            else await Promise.all(batch.map((key) => this.adapter.del(key)));\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    /**\n     * Adds `key` to each tag's index, for as long as the entry lives. With an\n     * adapter that has `sadd` it is one atomic step per tag, whatever the size\n     * of the index. Otherwise a JSON list is rewritten, one set() at a time per\n     * index key (concurrent set() calls used to both read the old index and\n     * one key was lost); that lock is per-process, so instances sharing a store\n     * can still race (see the docs).\n     */\n    private async indexTags(key: string, tags: string[], ttl: number | undefined): Promise<void> {\n        const adapter = this.adapter;\n        await Promise.all(\n            tags.map((tag) => {\n                if (adapter.sadd && adapter.sdrain) return adapter.sadd(this.tagSetKey(tag), key, ttl || undefined);\n                const listKey = this.tagListKey(tag);\n                return withLock(adapter, listKey, () => this.addToList(listKey, key, ttl));\n            }),\n        );\n    }\n\n    /**\n     * Rewriting the whole list on every set() made each one slower than the\n     * last, and expired keys were never dropped: they are now, the list expires\n     * with its last entry, and past MAX_TAG_LIST the oldest entries are deleted\n     * with their data (a deleted entry needs no invalidating).\n     */\n    private async addToList(listKey: string, key: string, ttl: number | undefined): Promise<void> {\n        const now = Date.now();\n        const expiresAt = ttl ? now + ttl * 1000 : 0;\n        const entries = parseTagList(await this.adapter.get(listKey)).filter(([, at]) => at === 0 || at > now);\n        const existing = entries.find(([listed]) => listed === key);\n        if (!existing) entries.push([key, expiresAt]);\n        // A key keeps its longest expiry: an earlier write may still be alive.\n        else if (existing[1] !== 0) existing[1] = expiresAt === 0 ? 0 : Math.max(existing[1], expiresAt);\n\n        const evicted = entries.length > MAX_TAG_LIST ? entries.splice(0, entries.length - MAX_TAG_LIST) : [];\n        await this.deleteKeys(evicted.map(([listed]) => listed));\n\n        // The list lives as long as its longest-lived entry (for good if one has no TTL).\n        const forever = entries.some(([, at]) => at === 0);\n        const last = entries.reduce((max, [, at]) => Math.max(max, at), 0);\n        const listTtl = forever ? undefined : (last - now) / 1000;\n        await this.adapter.set(listKey, JSON.stringify(entries), listTtl);\n    }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@iskra-bun/cache-kit",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Cache de aplicación de alto nivel para Iskra, construido sobre @iskra-bun/kv-kit.",
     "keywords": [
         "iskra",
@@ -19,6 +19,9 @@
     },
     "homepage": "https://github.com/fearful/iskra/tree/main/packages/cache-kit#readme",
     "bugs": "https://github.com/fearful/iskra/issues",
+    "engines": {
+        "bun": ">=1.3.0"
+    },
     "type": "module",
     "main": "./dist/index.js",
     "module": "./dist/index.js",
@@ -46,8 +49,8 @@
         "build": "tsup --config ../../tsup.config.ts"
     },
     "dependencies": {
-        "@iskra-bun/core": "0.1.1",
-        "@iskra-bun/kv-kit": "0.2.0"
+        "@iskra-bun/core": "^0.2.0",
+        "@iskra-bun/kv-kit": "^0.3.0"
     },
     "devDependencies": {
         "@types/bun": "^1.3.5",

package/src/cache.ts

@@ -1,40 +1,104 @@
 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__:';
+/** A tag's index as an expiring set, with adapters that have `sadd`/`sdrain`. */
+const TAG_SET_PREFIX = '__cache_tags__:';
+
+/** A tag's index as a JSON list: with other adapters, and every index written before 0.x. */
+const TAG_LIST_PREFIX = '__cache_tag__:';
+
+/**
+ * Data keys and namespaces may not reach the tag indexes: a key such as
+ * `__cache_tag__:perms` overwrote the index, and invalidateTag('perms') then
+ * deleted whatever keys it listed.
+ */
+const RESERVED = /(?:^|:)__cache_tags?__:/;
+
+/** Longest JSON tag index: beyond it, the oldest entries are deleted along with their data. */
+const MAX_TAG_LIST = 10_000;
+
+/** Keys deleted per call when a tag is invalidated. */
+const DELETE_BATCH = 1000;
 
 /** Keys that enable prototype-pollution when an object is later deep-merged. */
 const DANGEROUS_KEYS = ['__proto__', 'constructor', 'prototype'] as const;
 
+/** One of them as a key in JSON.stringify's output, which escapes none of their characters. */
+const DANGEROUS_KEY_TEXT = /"(?:__proto__|constructor|prototype)":/;
+
+class PollutionError extends Error {}
+
+/** A JSON tag index entry: the key and its expiry (ms since the epoch, 0 for none). */
+type TagEntry = [key: string, expiresAt: number];
+
+/** Pending tag-index updates per adapter (shared by its namespaced caches) and key. */
+const indexLocks = new WeakMap<object, Map<string, Promise<unknown>>>();
+
+/** Runs `fn` after the previous `fn` for the same adapter and key has settled. */
+function withLock<T>(adapter: object, key: string, fn: () => Promise<T>): Promise<T> {
+    let locks = indexLocks.get(adapter);
+    if (!locks) indexLocks.set(adapter, (locks = new Map()));
+    const previous = locks.get(key) ?? Promise.resolve();
+    const result = previous.then(fn, fn);
+    const settled = result.then(
+        () => undefined,
+        () => undefined,
+    );
+    locks.set(key, settled);
+    void settled.then(() => {
+        if (locks.get(key) === settled) locks.delete(key);
+    });
+    return result;
+}
+
 /**
- * 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.
+ * Parses cached JSON, throwing if any object in it 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. The reviver sees every key as
+ * parsed, so an escaped spelling such as `"\u005f_proto__"` is caught too
+ * (a check of the raw text for `"__proto__"` missed it).
  */
-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).`
-                );
-            }
+function parseSafely(raw: string): unknown {
+    return JSON.parse(raw, function (key, value) {
+        if ((DANGEROUS_KEYS as readonly string[]).includes(key)) {
+            throw new PollutionError(
+                `cache-kit: refusing to deserialize value containing the ` +
+                    `unsafe key "${key}" (prototype-pollution risk).`,
+            );
         }
+        return value;
+    });
+}
+
+/** Whether get() would refuse this serialized value (see parseSafely). */
+function isPolluted(serialized: string | undefined): boolean {
+    if (serialized === undefined || !DANGEROUS_KEY_TEXT.test(serialized)) return false;
+    try {
+        parseSafely(serialized);
+        return false;
+    } catch (error) {
+        return error instanceof PollutionError;
     }
 }
 
-/** 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)
-    );
+/** A JSON tag index; before 0.x its entries were bare keys, with no expiry. */
+function parseTagList(raw: unknown): TagEntry[] {
+    if (typeof raw !== 'string') return [];
+    let list: unknown;
+    try {
+        list = JSON.parse(raw);
+    } catch {
+        return [];
+    }
+    if (!Array.isArray(list)) return [];
+    return list.flatMap((entry): TagEntry[] => {
+        if (typeof entry === 'string') return [[entry, 0]];
+        if (Array.isArray(entry) && typeof entry[0] === 'string' && typeof entry[1] === 'number') {
+            return [[entry[0], entry[1]]];
+        }
+        return [];
+    });
 }
 
 /**
@@ -70,6 +134,9 @@ export class Cache {
         this.adapter = adapter ?? new MemoryAdapter();
         this.prefix = options.namespace ? `${options.namespace}:` : '';
         this.defaultTtl = options.defaultTtl;
+        if (RESERVED.test(this.prefix)) {
+            throw new Error(`cache-kit: the namespace "${options.namespace}" is reserved for tag indexes`);
+        }
     }
 
     // -------------------------------------------------------------------------
@@ -77,11 +144,17 @@ export class Cache {
     // -------------------------------------------------------------------------
 
     private prefixKey(key: string): string {
-        return `${this.prefix}${key}`;
+        const full = `${this.prefix}${key}`;
+        if (RESERVED.test(full)) throw new Error(`cache-kit: the key "${key}" is reserved for tag indexes`);
+        return full;
+    }
+
+    private tagSetKey(tag: string): string {
+        return `${this.prefix}${TAG_SET_PREFIX}${tag}`;
     }
 
-    private tagIndexKey(tag: string): string {
-        return `${this.prefix}${TAG_INDEX_PREFIX}${tag}`;
+    private tagListKey(tag: string): string {
+        return `${this.prefix}${TAG_LIST_PREFIX}${tag}`;
     }
 
     // -------------------------------------------------------------------------
@@ -90,25 +163,27 @@ export class Cache {
 
     /**
      * Retrieve a cached value by key.
-     * Returns `undefined` when the key is absent or has expired.
+     * Returns `undefined` when the key is absent or has expired, or when the
+     * stored value carries a prototype-pollution key (the entry is deleted).
      */
     async get<T = unknown>(key: string): Promise<T | undefined> {
-        const raw = await this.adapter.get(this.prefixKey(key));
+        const dataKey = this.prefixKey(key);
+        const raw = await this.adapter.get(dataKey);
         if (raw === undefined || raw === null) return undefined;
 
-        const text = raw as string;
-        let parsed: unknown;
         try {
-            parsed = JSON.parse(text);
-        } catch {
+            return parseSafely(raw as string) as T;
+        } catch (error) {
+            if (error instanceof PollutionError) {
+                // A miss: thrown, it failed every read until the TTL ran out
+                // (never without one), and remember() did not refetch.
+                await this.adapter.del(dataKey);
+                return undefined;
+            }
             throw new Error(
-                `cache-kit: failed to deserialize value for key "${key}". ` +
-                'The stored value is not valid JSON.'
+                `cache-kit: failed to deserialize value for key "${key}". ` + 'The stored value is not valid JSON.',
             );
         }
-
-        assertNoPollution(text, parsed);
-        return parsed as T;
     }
 
     /**
@@ -121,13 +196,32 @@ export class Cache {
      */
     async set<T>(key: string, value: T, options?: number | SetOptions): Promise<void> {
         const { ttl, tags } = this.resolveSetOptions(options);
+        const dataKey = this.prefixKey(key);
         const serialized = JSON.stringify(value);
         const effectiveTtl = ttl ?? this.defaultTtl;
+        if (effectiveTtl !== undefined && effectiveTtl !== 0 && !(effectiveTtl > 0 && Number.isFinite(effectiveTtl))) {
+            throw new RangeError(
+                `cache-kit: invalid TTL ${String(effectiveTtl)}: expected a positive number of seconds`,
+            );
+        }
 
-        await this.adapter.set(this.prefixKey(key), serialized, effectiveTtl);
+        // get() could never return it: nothing is stored (and the old value goes).
+        if (isPolluted(serialized)) {
+            await this.adapter.del(dataKey);
+            return;
+        }
+
+        await this.adapter.set(dataKey, serialized, effectiveTtl);
 
         if (tags && tags.length > 0) {
-            await this.indexTags(key, tags);
+            try {
+                await this.indexTags(key, tags, effectiveTtl);
+            } catch (err) {
+                // An entry its tags do not list would outlive invalidateTag():
+                // drop it and report the failure.
+                await this.adapter.del(dataKey).catch(() => {});
+                throw err;
+            }
         }
     }
 
@@ -146,29 +240,22 @@ export class Cache {
     }
 
     /**
-     * Flush the **entire** backing store shared by this Cache and every other
-     * Cache built on the same adapter.
+     * Delete every entry of this cache: its namespace (with the namespaces and
+     * tag indexes under it), or all the adapter's keys for a root cache. It
+     * runs the adapter's `clear()`: a KVManager clears its own namespace, and
+     * on Redis never the whole database unless `flushDb` allows it.
      *
-     * 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.
+     * It used to recycle the adapter (disconnect + connect): on Redis that
+     * deleted nothing, and a reconnect failing during a blip left the shared
+     * adapter dead after Redis recovered.
      *
-     * @throws Error when called on a namespaced Cache (a prefix is set).
+     * @throws Error when the adapter has no `clear()`.
      */
     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.'
-            );
+        if (!this.adapter.clear) {
+            throw new Error(`cache-kit: the "${this.adapter.id}" adapter cannot clear its keys (it has no clear())`);
         }
-        await this.adapter.disconnect();
-        await this.adapter.connect();
+        await this.adapter.clear(this.prefix);
     }
 
     // -------------------------------------------------------------------------
@@ -180,6 +267,8 @@ export class Cache {
      * store the result with the given TTL, and return it.
      *
      * The fallback is called **exactly once** on a cache miss — never on a hit.
+     * An error it throws is rethrown as is (so its class, status or code still
+     * reach the caller's error handling) and nothing is cached.
      *
      * @param key      Cache key.
      * @param ttl      TTL in seconds for the stored value.
@@ -189,15 +278,7 @@ export class Cache {
         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)}`
-            );
-        }
-
+        const value = await fallback();
         await this.set(key, value, { ttl });
         return value;
     }
@@ -216,21 +297,31 @@ export class Cache {
      * 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;
+        const listKey = this.tagListKey(tag);
+        await withLock(this.adapter, listKey, async () => {
+            // The JSON list too with an adapter that has sets: entries tagged
+            // before 0.x are listed there.
+            const keys = await this.drainList(listKey);
+            if (this.adapter.sdrain) keys.push(...(await this.adapter.sdrain(this.tagSetKey(tag))));
+            await this.deleteKeys(keys);
+        });
+    }
 
-        let keys: string[];
-        try {
-            keys = JSON.parse(raw as string) as string[];
-        } catch {
-            keys = [];
-        }
+    private async drainList(listKey: string): Promise<string[]> {
+        const raw = await this.adapter.get(listKey);
+        if (raw === null || raw === undefined) return [];
+        await this.adapter.del(listKey);
+        return parseTagList(raw).map(([key]) => key);
+    }
 
-        await Promise.all([
-            ...keys.map((k) => this.adapter.del(this.prefixKey(k))),
-            this.adapter.del(indexKey),
-        ]);
+    /** Deletes the entries of `keys` (relative to this cache), in batches; never a tag index. */
+    private async deleteKeys(keys: string[]): Promise<void> {
+        const full = [...new Set(keys)].map((key) => `${this.prefix}${key}`).filter((key) => !RESERVED.test(key));
+        for (let i = 0; i < full.length; i += DELETE_BATCH) {
+            const batch = full.slice(i, i + DELETE_BATCH);
+            if (this.adapter.mdel) await this.adapter.mdel(batch);
+            else await Promise.all(batch.map((key) => this.adapter.del(key)));
+        }
     }
 
     // -------------------------------------------------------------------------
@@ -267,22 +358,47 @@ export class Cache {
         return options;
     }
 
-    private async indexTags(key: string, tags: string[]): Promise<void> {
+    /**
+     * Adds `key` to each tag's index, for as long as the entry lives. With an
+     * adapter that has `sadd` it is one atomic step per tag, whatever the size
+     * of the index. Otherwise a JSON list is rewritten, one set() at a time per
+     * index key (concurrent set() calls used to both read the old index and
+     * one key was lost); that lock is per-process, so instances sharing a store
+     * can still race (see the docs).
+     */
+    private async indexTags(key: string, tags: string[], ttl: number | undefined): Promise<void> {
+        const adapter = this.adapter;
         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));
-            })
+            tags.map((tag) => {
+                if (adapter.sadd && adapter.sdrain) return adapter.sadd(this.tagSetKey(tag), key, ttl || undefined);
+                const listKey = this.tagListKey(tag);
+                return withLock(adapter, listKey, () => this.addToList(listKey, key, ttl));
+            }),
         );
     }
+
+    /**
+     * Rewriting the whole list on every set() made each one slower than the
+     * last, and expired keys were never dropped: they are now, the list expires
+     * with its last entry, and past MAX_TAG_LIST the oldest entries are deleted
+     * with their data (a deleted entry needs no invalidating).
+     */
+    private async addToList(listKey: string, key: string, ttl: number | undefined): Promise<void> {
+        const now = Date.now();
+        const expiresAt = ttl ? now + ttl * 1000 : 0;
+        const entries = parseTagList(await this.adapter.get(listKey)).filter(([, at]) => at === 0 || at > now);
+        const existing = entries.find(([listed]) => listed === key);
+        if (!existing) entries.push([key, expiresAt]);
+        // A key keeps its longest expiry: an earlier write may still be alive.
+        else if (existing[1] !== 0) existing[1] = expiresAt === 0 ? 0 : Math.max(existing[1], expiresAt);
+
+        const evicted = entries.length > MAX_TAG_LIST ? entries.splice(0, entries.length - MAX_TAG_LIST) : [];
+        await this.deleteKeys(evicted.map(([listed]) => listed));
+
+        // The list lives as long as its longest-lived entry (for good if one has no TTL).
+        const forever = entries.some(([, at]) => at === 0);
+        const last = entries.reduce((max, [, at]) => Math.max(max, at), 0);
+        const listTtl = forever ? undefined : (last - now) / 1000;
+        await this.adapter.set(listKey, JSON.stringify(entries), listTtl);
+    }
 }

package/src/memory-adapter.ts

@@ -1,5 +1,16 @@
 import type { KVAdapter } from './types';
 
+/** setTimeout's limit: a longer delay (a TTL over ~24.8 days) fires at once. */
+const MAX_TIMEOUT_MS = 2 ** 31 - 1;
+
+/** An expiring set: each member's expiry (ms since the epoch, Infinity for none). */
+interface ExpiringSet {
+    members: Map<string, number>;
+    expiresAt: number;
+    /** Size at which expired members are next dropped. */
+    pruneAt: number;
+}
+
 /**
  * Lightweight in-memory {@link KVAdapter} used as the default backing store
  * when no adapter is supplied to the {@link Cache} constructor.
@@ -10,6 +21,7 @@ import type { KVAdapter } from './types';
 export class MemoryAdapter implements KVAdapter {
     readonly id = 'memory';
     private store = new Map<string, unknown>();
+    private sets = new Map<string, ExpiringSet>();
     private timers = new Map<string, ReturnType<typeof setTimeout>>();
 
     connect(): void {
@@ -20,6 +32,7 @@ export class MemoryAdapter implements KVAdapter {
         for (const timer of this.timers.values()) clearTimeout(timer);
         this.timers = new Map();
         this.store = new Map();
+        this.sets = new Map();
     }
 
     async get<T = unknown>(key: string): Promise<T | undefined> {
@@ -28,20 +41,31 @@ export class MemoryAdapter implements KVAdapter {
 
     async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {
         this.clearTimer(key);
+        this.sets.delete(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);
-        }
+        if (ttl && ttl > 0 && Number.isFinite(ttl)) this.expireIn(key, ttl * 1000);
+    }
+
+    /** Arms the expiry timer, in steps when the delay exceeds setTimeout's limit. */
+    private expireIn(key: string, ms: number): void {
+        const step = Math.min(ms, MAX_TIMEOUT_MS);
+        const timer = setTimeout(() => {
+            if (ms > step) {
+                this.expireIn(key, ms - step);
+                return;
+            }
+            this.store.delete(key);
+            this.sets.delete(key);
+            this.timers.delete(key);
+        }, step);
+        timer.unref?.();
+        this.timers.set(key, timer);
     }
 
     async del(key: string): Promise<void> {
         this.clearTimer(key);
         this.store.delete(key);
+        this.sets.delete(key);
     }
 
     private clearTimer(key: string): void {
@@ -53,6 +77,44 @@ export class MemoryAdapter implements KVAdapter {
     }
 
     async has(key: string): Promise<boolean> {
-        return this.store.has(key);
+        return this.store.has(key) || this.sets.has(key);
+    }
+
+    async clear(prefix = ''): Promise<void> {
+        for (const key of [...this.store.keys(), ...this.sets.keys()]) {
+            if (key.startsWith(prefix)) await this.del(key);
+        }
+    }
+
+    async sadd(key: string, member: string, ttl?: number): Promise<void> {
+        const now = Date.now();
+        const expiresAt = ttl && ttl > 0 && Number.isFinite(ttl) ? now + ttl * 1000 : Infinity;
+        let set = this.sets.get(key);
+        if (!set) {
+            this.store.delete(key);
+            set = { members: new Map(), expiresAt: 0, pruneAt: 64 };
+            this.sets.set(key, set);
+        }
+        // A member keeps its latest expiry, and expired members go each time
+        // the set doubles (O(1) per add on average), as in kv-kit.
+        set.members.set(member, Math.max(set.members.get(member) ?? 0, expiresAt));
+        if (set.members.size >= set.pruneAt) {
+            for (const [name, at] of set.members) if (at <= now) set.members.delete(name);
+            set.pruneAt = Math.max(64, set.members.size * 2);
+        }
+        if (expiresAt > set.expiresAt) {
+            set.expiresAt = expiresAt;
+            this.clearTimer(key);
+            if (expiresAt !== Infinity) this.expireIn(key, expiresAt - now);
+        }
+    }
+
+    async sdrain(key: string): Promise<string[]> {
+        const set = this.sets.get(key);
+        if (!set) return [];
+        this.sets.delete(key);
+        this.clearTimer(key);
+        const now = Date.now();
+        return [...set.members].filter(([, at]) => at > now).map(([name]) => name);
     }
 }