@lacspace/llm-cache 1.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+Lacspace Free Licence
+Version 1.0, August 2026
+
+Copyright (c) 2026 Lacspace
+
+PREAMBLE
+
+This software is published by Lacspace under the Lacspace Free Licence — a free,
+permissive licence that lets you use this software for any purpose, including in
+commercial products and services, at no cost. It grants the same freedoms as
+common permissive open-source licences; the only condition is that this notice
+travels with the software. The canonical, always-current text of this licence is
+maintained at https://lacspace.com/licenses/lacspace-free-1.0
+
+GRANT OF RIGHTS
+
+Permission is hereby granted, free of charge, to any person or organisation
+obtaining a copy of this software and its associated documentation and data files
+(the "Software"), to deal in the Software without restriction, including without
+limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the conditions below. These rights are
+granted for any purpose, personal or commercial, and are perpetual, worldwide,
+non-exclusive, and royalty-free.
+
+CONDITIONS
+
+The above copyright notice, this permission notice, and the name of this licence
+("Lacspace Free Licence") shall be included in all copies or substantial portions
+of the Software.
+
+TRADEMARKS
+
+This licence does not grant permission to use the trade names, trademarks, service
+marks, logos, or product names of Lacspace, except as required to reproduce the
+notice above or to describe the origin of the Software in a truthful manner.
+
+DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+The Lacspace Free Licence is a source-available, permissive licence and is not (as
+of this version) an OSI-approved licence. In substance it grants the same freedoms
+as the MIT Licence. Learn more at https://lacspace.com/licenses

package/README.md

@@ -0,0 +1,31 @@
+# @lacspace/llm-cache
+
+**Never pay twice for the same LLM call.** A content-hash cache keyed by `(model family, prompt version, normalized input)`, so identical requests, retries after a 429, and repeated rewrites are served from cache. Pluggable async store (in-memory LRU built in; Mongo/Redis/KV via a tiny interface), TTL, stale-if-error, and a `wrap()` memoizer. Zero dependencies, isomorphic.
+
+```bash
+npm i @lacspace/llm-cache
+```
+
+```ts
+import { createLlmCache, memoryStore } from "@lacspace/llm-cache";
+
+const cache = createLlmCache({ store: memoryStore(), ttlMs: 24 * 3600_000, promptVersion: "v3" });
+
+const pack = await cache.wrap(
+  { input: condensedSources, model: "gemini", variant: { lang: "ne" } },
+  () => callGemini(condensedSources),          // only runs on a miss
+  { staleIfError: true },                       // 429? serve the last good result
+);
+
+cache.stats(); // { hits, misses, sets }
+```
+
+- **Stable key** across runtimes via a wide (128-bit) dependency-free content hash; whitespace-normalized input by default.
+- **`wrap(input, fn)`** memoizes an async call: the retry that a rate-limit forces you into costs nothing.
+- **Pluggable store** — implement `{ get, set, delete }` (sync or async) over Mongo/Redis/KV to share the cache across PM2 processes or hosts; `kvStore`-style adapters are trivial.
+- **TTL + stale-if-error** — expire results, but fall back to the last good one when the provider is down.
+
+Bump `promptVersion` when your template changes and old results retire automatically. Exports `contentHash`, `memoryStore`, and the `CacheStore` interface.
+
+## Licence
+[Lacspace Free Licence v1.0](https://developer.lacspace.com/licenses/lacspace-free-1.0) — free for personal and commercial use.

package/dist/index.cjs

@@ -0,0 +1,140 @@
+'use strict';
+
+// src/hash.ts
+var P = 1099511628211n;
+var MASK = (1n << 64n) - 1n;
+function fnv(input, basis) {
+  let h = basis;
+  for (let i = 0; i < input.length; i++) {
+    h ^= BigInt(input.charCodeAt(i));
+    h = h * P & MASK;
+  }
+  return h;
+}
+function hex16(n) {
+  return n.toString(16).padStart(16, "0");
+}
+function contentHash(input) {
+  return hex16(fnv(input, 14695981039346656037n)) + hex16(fnv(input, 1469598103934665603n));
+}
+
+// src/stores.ts
+function memoryStore(options = {}) {
+  const max = options.maxEntries ?? 1e3;
+  const map = /* @__PURE__ */ new Map();
+  const evictExpired = (now) => {
+    for (const [k, v] of map) if (v.expiresAt !== null && v.expiresAt <= now) map.delete(k);
+  };
+  return {
+    get(key) {
+      const rec = map.get(key);
+      if (!rec) return null;
+      if (rec.expiresAt !== null && rec.expiresAt <= Date.now()) {
+        map.delete(key);
+        return null;
+      }
+      map.delete(key);
+      map.set(key, rec);
+      return rec;
+    },
+    set(key, rec) {
+      const now = Date.now();
+      evictExpired(now);
+      map.delete(key);
+      map.set(key, rec);
+      while (map.size > max) {
+        const oldest = map.keys().next().value;
+        if (oldest === void 0) break;
+        map.delete(oldest);
+      }
+    },
+    delete(key) {
+      map.delete(key);
+    },
+    size() {
+      return map.size;
+    },
+    clear() {
+      map.clear();
+    }
+  };
+}
+
+// src/index.ts
+var defaultNormalize = (s) => s.replace(/\s+/g, " ").trim();
+function variantString(v) {
+  if (v === void 0) return "";
+  if (typeof v === "string") return v;
+  return JSON.stringify(v, Object.keys(v).sort());
+}
+function createLlmCache(options = {}) {
+  const store = options.store ?? memoryStore();
+  const ns = options.namespace ?? "llm";
+  const normalize = options.normalize ?? defaultNormalize;
+  let hits = 0;
+  let misses = 0;
+  let sets = 0;
+  const key = (input) => {
+    const parts = [
+      ns,
+      input.model ?? "",
+      input.promptVersion ?? options.promptVersion ?? "",
+      variantString(input.variant),
+      normalize(input.input ?? "")
+    ].join("\0");
+    return `${ns}:${contentHash(parts)}`;
+  };
+  const get = async (input) => {
+    const k = key(input);
+    const rec = await store.get(k);
+    if (rec && (rec.expiresAt === null || rec.expiresAt > Date.now())) {
+      hits++;
+      return { hit: true, value: rec.value, key: k, record: rec };
+    }
+    misses++;
+    return { hit: false, value: null, key: k, record: null };
+  };
+  const setAt = async (k, value, ttlMs, meta) => {
+    const now = Date.now();
+    const ttl = ttlMs ?? options.ttlMs ?? 0;
+    const record = { value, storedAt: now, expiresAt: ttl > 0 ? now + ttl : null, meta };
+    await store.set(k, record);
+    sets++;
+  };
+  return {
+    key,
+    get,
+    async set(input, value, opts) {
+      await setAt(key(input), value, opts?.ttlMs, opts?.meta);
+    },
+    async delete(input) {
+      await store.delete(key(input));
+    },
+    async wrap(input, fn, opts) {
+      const k = key(input);
+      const rec = await store.get(k);
+      if (rec && (rec.expiresAt === null || rec.expiresAt > Date.now())) {
+        hits++;
+        return rec.value;
+      }
+      misses++;
+      try {
+        const value = await fn();
+        await setAt(k, value, opts?.ttlMs, opts?.meta);
+        return value;
+      } catch (err) {
+        if ((opts?.staleIfError ?? false) && rec) return rec.value;
+        throw err;
+      }
+    },
+    stats() {
+      return { hits, misses, sets };
+    }
+  };
+}
+
+exports.contentHash = contentHash;
+exports.createLlmCache = createLlmCache;
+exports.memoryStore = memoryStore;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hash.ts","../src/stores.ts","../src/index.ts"],"names":[],"mappings":";;;AAGA,IAAM,CAAA,GAAI,cAAA;AACV,IAAM,IAAA,GAAA,CAAQ,MAAM,GAAA,IAAO,EAAA;AAE3B,SAAS,GAAA,CAAI,OAAe,KAAA,EAAuB;AACjD,EAAA,IAAI,CAAA,GAAI,KAAA;AACR,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,KAAA,CAAM,QAAQ,CAAA,EAAA,EAAK;AACrC,IAAA,CAAA,IAAK,MAAA,CAAO,KAAA,CAAM,UAAA,CAAW,CAAC,CAAC,CAAA;AAC/B,IAAA,CAAA,GAAK,IAAI,CAAA,GAAK,IAAA;AAAA,EAChB;AACA,EAAA,OAAO,CAAA;AACT;AAEA,SAAS,MAAM,CAAA,EAAmB;AAChC,EAAA,OAAO,EAAE,QAAA,CAAS,EAAE,CAAA,CAAE,QAAA,CAAS,IAAI,GAAG,CAAA;AACxC;AAGO,SAAS,YAAY,KAAA,EAAuB;AACjD,EAAA,OAAO,KAAA,CAAM,GAAA,CAAI,KAAA,EAAO,qBAAqB,CAAC,IAAI,KAAA,CAAM,GAAA,CAAI,KAAA,EAAO,oBAAoB,CAAC,CAAA;AAC1F;;;ACPO,SAAS,WAAA,CAAY,OAAA,GAAmC,EAAC,EAAgB;AAC9E,EAAA,MAAM,GAAA,GAAM,QAAQ,UAAA,IAAc,GAAA;AAClC,EAAA,MAAM,GAAA,uBAAU,GAAA,EAAyB;AAEzC,EAAA,MAAM,YAAA,GAAe,CAAC,GAAA,KAAgB;AACpC,IAAA,KAAA,MAAW,CAAC,CAAA,EAAG,CAAC,CAAA,IAAK,KAAK,IAAI,CAAA,CAAE,SAAA,KAAc,IAAA,IAAQ,CAAA,CAAE,SAAA,IAAa,GAAA,EAAK,GAAA,CAAI,OAAO,CAAC,CAAA;AAAA,EACxF,CAAA;AAEA,EAAA,OAAO;AAAA,IACL,IAAI,GAAA,EAAK;AACP,MAAA,MAAM,GAAA,GAAM,GAAA,CAAI,GAAA,CAAI,GAAG,CAAA;AACvB,MAAA,IAAI,CAAC,KAAK,OAAO,IAAA;AACjB,MAAA,IAAI,IAAI,SAAA,KAAc,IAAA,IAAQ,IAAI,SAAA,IAAa,IAAA,CAAK,KAAI,EAAG;AACzD,QAAA,GAAA,CAAI,OAAO,GAAG,CAAA;AACd,QAAA,OAAO,IAAA;AAAA,MACT;AAEA,MAAA,GAAA,CAAI,OAAO,GAAG,CAAA;AACd,MAAA,GAAA,CAAI,GAAA,CAAI,KAAK,GAAG,CAAA;AAChB,MAAA,OAAO,GAAA;AAAA,IACT,CAAA;AAAA,IACA,GAAA,CAAI,KAAK,GAAA,EAAK;AACZ,MAAA,MAAM,GAAA,GAAM,KAAK,GAAA,EAAI;AACrB,MAAA,YAAA,CAAa,GAAG,CAAA;AAChB,MAAA,GAAA,CAAI,OAAO,GAAG,CAAA;AACd,MAAA,GAAA,CAAI,GAAA,CAAI,KAAK,GAAG,CAAA;AAChB,MAAA,OAAO,GAAA,CAAI,OAAO,GAAA,EAAK;AACrB,QAAA,MAAM,MAAA,GAAS,GAAA,CAAI,IAAA,EAAK,CAAE,MAAK,CAAE,KAAA;AACjC,QAAA,IAAI,WAAW,MAAA,EAAW;AAC1B,QAAA,GAAA,CAAI,OAAO,MAAM,CAAA;AAAA,MACnB;AAAA,IACF,CAAA;AAAA,IACA,OAAO,GAAA,EAAK;AACV,MAAA,GAAA,CAAI,OAAO,GAAG,CAAA;AAAA,IAChB,CAAA;AAAA,IACA,IAAA,GAAO;AACL,MAAA,OAAO,GAAA,CAAI,IAAA;AAAA,IACb,CAAA;AAAA,IACA,KAAA,GAAQ;AACN,MAAA,GAAA,CAAI,KAAA,EAAM;AAAA,IACZ;AAAA,GACF;AACF;;;ACGA,IAAM,gBAAA,GAAmB,CAAC,CAAA,KAAsB,CAAA,CAAE,QAAQ,MAAA,EAAQ,GAAG,EAAE,IAAA,EAAK;AAE5E,SAAS,cAAc,CAAA,EAAqC;AAC1D,EAAA,IAAI,CAAA,KAAM,QAAW,OAAO,EAAA;AAC5B,EAAA,IAAI,OAAO,CAAA,KAAM,QAAA,EAAU,OAAO,CAAA;AAElC,EAAA,OAAO,IAAA,CAAK,UAAU,CAAA,EAAG,MAAA,CAAO,KAAK,CAAC,CAAA,CAAE,MAAM,CAAA;AAChD;AAEO,SAAS,cAAA,CAAe,OAAA,GAA2B,EAAC,EAAa;AACtE,EAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,KAAA,IAAS,WAAA,EAAY;AAC3C,EAAA,MAAM,EAAA,GAAK,QAAQ,SAAA,IAAa,KAAA;AAChC,EAAA,MAAM,SAAA,GAAY,QAAQ,SAAA,IAAa,gBAAA;AACvC,EAAA,IAAI,IAAA,GAAO,CAAA;AACX,EAAA,IAAI,MAAA,GAAS,CAAA;AACb,EAAA,IAAI,IAAA,GAAO,CAAA;AAEX,EAAA,MAAM,GAAA,GAAM,CAAC,KAAA,KAAiC;AAC5C,IAAA,MAAM,KAAA,GAAQ;AAAA,MACZ,EAAA;AAAA,MACA,MAAM,KAAA,IAAS,EAAA;AAAA,MACf,KAAA,CAAM,aAAA,IAAiB,OAAA,CAAQ,aAAA,IAAiB,EAAA;AAAA,MAChD,aAAA,CAAc,MAAM,OAAO,CAAA;AAAA,MAC3B,SAAA,CAAU,KAAA,CAAM,KAAA,IAAS,EAAE;AAAA,KAC7B,CAAE,KAAK,IAAQ,CAAA;AACf,IAAA,OAAO,CAAA,EAAG,EAAE,CAAA,CAAA,EAAI,WAAA,CAAY,KAAK,CAAC,CAAA,CAAA;AAAA,EACpC,CAAA;AAEA,EAAA,MAAM,GAAA,GAAM,OAAU,KAAA,KAAqD;AACzE,IAAA,MAAM,CAAA,GAAI,IAAI,KAAK,CAAA;AACnB,IAAA,MAAM,GAAA,GAAO,MAAM,KAAA,CAAM,GAAA,CAAI,CAAC,CAAA;AAC9B,IAAA,IAAI,GAAA,KAAQ,IAAI,SAAA,KAAc,IAAA,IAAQ,IAAI,SAAA,GAAY,IAAA,CAAK,KAAI,CAAA,EAAI;AACjE,MAAA,IAAA,EAAA;AACA,MAAA,OAAO,EAAE,KAAK,IAAA,EAAM,KAAA,EAAO,IAAI,KAAA,EAAO,GAAA,EAAK,CAAA,EAAG,MAAA,EAAQ,GAAA,EAAI;AAAA,IAC5D;AACA,IAAA,MAAA,EAAA;AACA,IAAA,OAAO,EAAE,KAAK,KAAA,EAAO,KAAA,EAAO,MAAM,GAAA,EAAK,CAAA,EAAG,QAAQ,IAAA,EAAK;AAAA,EACzD,CAAA;AAEA,EAAA,MAAM,KAAA,GAAQ,OAAU,CAAA,EAAW,KAAA,EAAU,OAA2B,IAAA,KAAkD;AACxH,IAAA,MAAM,GAAA,GAAM,KAAK,GAAA,EAAI;AACrB,IAAA,MAAM,GAAA,GAAM,KAAA,IAAS,OAAA,CAAQ,KAAA,IAAS,CAAA;AACtC,IAAA,MAAM,MAAA,GAAyB,EAAE,KAAA,EAAO,QAAA,EAAU,GAAA,EAAK,SAAA,EAAW,GAAA,GAAM,CAAA,GAAI,GAAA,GAAM,GAAA,GAAM,IAAA,EAAM,IAAA,EAAK;AACnG,IAAA,MAAM,KAAA,CAAM,GAAA,CAAI,CAAA,EAAG,MAAqB,CAAA;AACxC,IAAA,IAAA,EAAA;AAAA,EACF,CAAA;AAEA,EAAA,OAAO;AAAA,IACL,GAAA;AAAA,IACA,GAAA;AAAA,IACA,MAAM,GAAA,CAAI,KAAA,EAAO,KAAA,EAAO,IAAA,EAAM;AAC5B,MAAA,MAAM,KAAA,CAAM,IAAI,KAAK,CAAA,EAAG,OAAO,IAAA,EAAM,KAAA,EAAO,MAAM,IAAI,CAAA;AAAA,IACxD,CAAA;AAAA,IACA,MAAM,OAAO,KAAA,EAAO;AAClB,MAAA,MAAM,KAAA,CAAM,MAAA,CAAO,GAAA,CAAI,KAAK,CAAC,CAAA;AAAA,IAC/B,CAAA;AAAA,IACA,MAAM,IAAA,CAAK,KAAA,EAAO,EAAA,EAAI,IAAA,EAAM;AAC1B,MAAA,MAAM,CAAA,GAAI,IAAI,KAAK,CAAA;AACnB,MAAA,MAAM,GAAA,GAAO,MAAM,KAAA,CAAM,GAAA,CAAI,CAAC,CAAA;AAC9B,MAAA,IAAI,GAAA,KAAQ,IAAI,SAAA,KAAc,IAAA,IAAQ,IAAI,SAAA,GAAY,IAAA,CAAK,KAAI,CAAA,EAAI;AACjE,QAAA,IAAA,EAAA;AACA,QAAA,OAAO,GAAA,CAAI,KAAA;AAAA,MACb;AACA,MAAA,MAAA,EAAA;AACA,MAAA,IAAI;AACF,QAAA,MAAM,KAAA,GAAQ,MAAM,EAAA,EAAG;AACvB,QAAA,MAAM,MAAM,CAAA,EAAG,KAAA,EAAO,IAAA,EAAM,KAAA,EAAO,MAAM,IAAI,CAAA;AAC7C,QAAA,OAAO,KAAA;AAAA,MACT,SAAS,GAAA,EAAK;AACZ,QAAA,IAAA,CAAK,IAAA,EAAM,YAAA,IAAgB,KAAA,KAAU,GAAA,SAAY,GAAA,CAAI,KAAA;AACrD,QAAA,MAAM,GAAA;AAAA,MACR;AAAA,IACF,CAAA;AAAA,IACA,KAAA,GAAQ;AACN,MAAA,OAAO,EAAE,IAAA,EAAM,MAAA,EAAQ,IAAA,EAAK;AAAA,IAC9B;AAAA,GACF;AACF","file":"index.cjs","sourcesContent":["// A wide, dependency-free content hash. Two independent FNV-1a passes (64-bit\n// each via BigInt, different offset bases) concatenated to 32 hex chars, so the\n// collision space is ~2^128 — ample for a cache key without pulling in crypto.\nconst P = 1099511628211n;\nconst MASK = (1n << 64n) - 1n;\n\nfunction fnv(input: string, basis: bigint): bigint {\n  let h = basis;\n  for (let i = 0; i < input.length; i++) {\n    h ^= BigInt(input.charCodeAt(i));\n    h = (h * P) & MASK;\n  }\n  return h;\n}\n\nfunction hex16(n: bigint): string {\n  return n.toString(16).padStart(16, \"0\");\n}\n\n/** Stable 128-bit hex digest of a string. Deterministic across runtimes. */\nexport function contentHash(input: string): string {\n  return hex16(fnv(input, 14695981039346656037n)) + hex16(fnv(input, 1469598103934665603n));\n}\n","import type { CacheRecord, CacheStore } from \"./types.js\";\n\n/**\n * In-memory store with TTL and an LRU cap. Good for a single process; for\n * multi-process (PM2) or cross-host sharing, pass a Mongo/Redis-backed store\n * that implements the same {@link CacheStore} interface.\n */\nexport interface MemoryStore extends CacheStore {\n  get(key: string): CacheRecord | null;\n  set(key: string, record: CacheRecord): void;\n  delete(key: string): void;\n  size(): number;\n  clear(): void;\n}\n\nexport function memoryStore(options: { maxEntries?: number } = {}): MemoryStore {\n  const max = options.maxEntries ?? 1000;\n  const map = new Map<string, CacheRecord>();\n\n  const evictExpired = (now: number) => {\n    for (const [k, v] of map) if (v.expiresAt !== null && v.expiresAt <= now) map.delete(k);\n  };\n\n  return {\n    get(key) {\n      const rec = map.get(key);\n      if (!rec) return null;\n      if (rec.expiresAt !== null && rec.expiresAt <= Date.now()) {\n        map.delete(key);\n        return null;\n      }\n      // LRU touch\n      map.delete(key);\n      map.set(key, rec);\n      return rec;\n    },\n    set(key, rec) {\n      const now = Date.now();\n      evictExpired(now);\n      map.delete(key);\n      map.set(key, rec);\n      while (map.size > max) {\n        const oldest = map.keys().next().value;\n        if (oldest === undefined) break;\n        map.delete(oldest);\n      }\n    },\n    delete(key) {\n      map.delete(key);\n    },\n    size() {\n      return map.size;\n    },\n    clear() {\n      map.clear();\n    },\n  };\n}\n","import { contentHash } from \"./hash.js\";\nimport { memoryStore } from \"./stores.js\";\nimport type { CacheRecord, CacheStore } from \"./types.js\";\n\nexport { contentHash } from \"./hash.js\";\nexport { memoryStore } from \"./stores.js\";\nexport type { MemoryStore } from \"./stores.js\";\nexport type { CacheRecord, CacheStore } from \"./types.js\";\n\n/** The dimensions that make one LLM request identical to another. */\nexport interface CacheKeyInput {\n  /** The prompt / input text (or a stable stringification of your messages). */\n  input: string;\n  /** Model family — different families should not share results (e.g. \"gemini\", \"groq-llama\"). */\n  model?: string;\n  /** Bump when your prompt template changes so old results are not reused. */\n  promptVersion?: string;\n  /** Extra key parts (temperature, tools, language…) that change the output. */\n  variant?: string | Record<string, unknown>;\n}\n\nexport interface LlmCacheOptions {\n  /** Where records live. Default: in-memory LRU (1000 entries). */\n  store?: CacheStore;\n  /** Default TTL in ms. Omit or 0 for no expiry. */\n  ttlMs?: number;\n  /** Global prompt version, overridable per call. */\n  promptVersion?: string;\n  /** Namespace prefix, so multiple caches can share one store. */\n  namespace?: string;\n  /** Normalize the input before hashing. Default: trim + collapse whitespace. */\n  normalize?: (input: string) => string;\n}\n\nexport interface CacheGetResult<T> {\n  hit: boolean;\n  value: T | null;\n  key: string;\n  record: CacheRecord<T> | null;\n}\n\nexport interface LlmCache {\n  /** Compute the content-hash key for an input (no store access). */\n  key(input: CacheKeyInput): string;\n  /** Look up a cached value. */\n  get<T = unknown>(input: CacheKeyInput): Promise<CacheGetResult<T>>;\n  /** Store a value, with an optional per-call TTL and metadata. */\n  set<T = unknown>(input: CacheKeyInput, value: T, opts?: { ttlMs?: number; meta?: Record<string, unknown> }): Promise<void>;\n  /** Remove one entry. */\n  delete(input: CacheKeyInput): Promise<void>;\n  /**\n   * Memoize an async LLM call: returns the cached value on a hit, otherwise runs\n   * `fn`, stores the result, and returns it. On a `fn` error, an unexpired\n   * record is returned if present (stale-if-error), else the error rethrows.\n   */\n  wrap<T>(input: CacheKeyInput, fn: () => Promise<T>, opts?: { ttlMs?: number; meta?: Record<string, unknown>; staleIfError?: boolean }): Promise<T>;\n  /** Hit/miss counters since creation. */\n  stats(): { hits: number; misses: number; sets: number };\n}\n\nconst defaultNormalize = (s: string): string => s.replace(/\\s+/g, \" \").trim();\n\nfunction variantString(v: CacheKeyInput[\"variant\"]): string {\n  if (v === undefined) return \"\";\n  if (typeof v === \"string\") return v;\n  // Stable stringify: sort keys.\n  return JSON.stringify(v, Object.keys(v).sort());\n}\n\nexport function createLlmCache(options: LlmCacheOptions = {}): LlmCache {\n  const store = options.store ?? memoryStore();\n  const ns = options.namespace ?? \"llm\";\n  const normalize = options.normalize ?? defaultNormalize;\n  let hits = 0;\n  let misses = 0;\n  let sets = 0;\n\n  const key = (input: CacheKeyInput): string => {\n    const parts = [\n      ns,\n      input.model ?? \"\",\n      input.promptVersion ?? options.promptVersion ?? \"\",\n      variantString(input.variant),\n      normalize(input.input ?? \"\"),\n    ].join(\"\\u0000\");\n    return `${ns}:${contentHash(parts)}`;\n  };\n\n  const get = async <T>(input: CacheKeyInput): Promise<CacheGetResult<T>> => {\n    const k = key(input);\n    const rec = (await store.get(k)) as CacheRecord<T> | null;\n    if (rec && (rec.expiresAt === null || rec.expiresAt > Date.now())) {\n      hits++;\n      return { hit: true, value: rec.value, key: k, record: rec };\n    }\n    misses++;\n    return { hit: false, value: null, key: k, record: null };\n  };\n\n  const setAt = async <T>(k: string, value: T, ttlMs: number | undefined, meta?: Record<string, unknown>): Promise<void> => {\n    const now = Date.now();\n    const ttl = ttlMs ?? options.ttlMs ?? 0;\n    const record: CacheRecord<T> = { value, storedAt: now, expiresAt: ttl > 0 ? now + ttl : null, meta };\n    await store.set(k, record as CacheRecord);\n    sets++;\n  };\n\n  return {\n    key,\n    get,\n    async set(input, value, opts) {\n      await setAt(key(input), value, opts?.ttlMs, opts?.meta);\n    },\n    async delete(input) {\n      await store.delete(key(input));\n    },\n    async wrap(input, fn, opts) {\n      const k = key(input);\n      const rec = (await store.get(k)) as CacheRecord | null;\n      if (rec && (rec.expiresAt === null || rec.expiresAt > Date.now())) {\n        hits++;\n        return rec.value as Awaited<ReturnType<typeof fn>>;\n      }\n      misses++;\n      try {\n        const value = await fn();\n        await setAt(k, value, opts?.ttlMs, opts?.meta);\n        return value;\n      } catch (err) {\n        if ((opts?.staleIfError ?? false) && rec) return rec.value as Awaited<ReturnType<typeof fn>>;\n        throw err;\n      }\n    },\n    stats() {\n      return { hits, misses, sets };\n    },\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,100 @@
+/** A stored cache record. `value` is whatever the LLM call returned (JSON-serializable). */
+interface CacheRecord<T = unknown> {
+    value: T;
+    /** Epoch ms when this expires, or null for no expiry. */
+    expiresAt: number | null;
+    /** Epoch ms when it was written. */
+    storedAt: number;
+    /** Optional metadata the caller attached (e.g. model, tokens). */
+    meta?: Record<string, unknown>;
+}
+/**
+ * A pluggable cache store. All methods may be sync or async. Implement this over
+ * Mongo, Redis, Cloudflare KV, etc. to share the cache across processes/hosts.
+ */
+interface CacheStore {
+    get(key: string): CacheRecord | null | Promise<CacheRecord | null>;
+    set(key: string, record: CacheRecord): void | Promise<void>;
+    delete(key: string): void | Promise<void>;
+}
+
+/** Stable 128-bit hex digest of a string. Deterministic across runtimes. */
+declare function contentHash(input: string): string;
+
+/**
+ * In-memory store with TTL and an LRU cap. Good for a single process; for
+ * multi-process (PM2) or cross-host sharing, pass a Mongo/Redis-backed store
+ * that implements the same {@link CacheStore} interface.
+ */
+interface MemoryStore extends CacheStore {
+    get(key: string): CacheRecord | null;
+    set(key: string, record: CacheRecord): void;
+    delete(key: string): void;
+    size(): number;
+    clear(): void;
+}
+declare function memoryStore(options?: {
+    maxEntries?: number;
+}): MemoryStore;
+
+/** The dimensions that make one LLM request identical to another. */
+interface CacheKeyInput {
+    /** The prompt / input text (or a stable stringification of your messages). */
+    input: string;
+    /** Model family — different families should not share results (e.g. "gemini", "groq-llama"). */
+    model?: string;
+    /** Bump when your prompt template changes so old results are not reused. */
+    promptVersion?: string;
+    /** Extra key parts (temperature, tools, language…) that change the output. */
+    variant?: string | Record<string, unknown>;
+}
+interface LlmCacheOptions {
+    /** Where records live. Default: in-memory LRU (1000 entries). */
+    store?: CacheStore;
+    /** Default TTL in ms. Omit or 0 for no expiry. */
+    ttlMs?: number;
+    /** Global prompt version, overridable per call. */
+    promptVersion?: string;
+    /** Namespace prefix, so multiple caches can share one store. */
+    namespace?: string;
+    /** Normalize the input before hashing. Default: trim + collapse whitespace. */
+    normalize?: (input: string) => string;
+}
+interface CacheGetResult<T> {
+    hit: boolean;
+    value: T | null;
+    key: string;
+    record: CacheRecord<T> | null;
+}
+interface LlmCache {
+    /** Compute the content-hash key for an input (no store access). */
+    key(input: CacheKeyInput): string;
+    /** Look up a cached value. */
+    get<T = unknown>(input: CacheKeyInput): Promise<CacheGetResult<T>>;
+    /** Store a value, with an optional per-call TTL and metadata. */
+    set<T = unknown>(input: CacheKeyInput, value: T, opts?: {
+        ttlMs?: number;
+        meta?: Record<string, unknown>;
+    }): Promise<void>;
+    /** Remove one entry. */
+    delete(input: CacheKeyInput): Promise<void>;
+    /**
+     * Memoize an async LLM call: returns the cached value on a hit, otherwise runs
+     * `fn`, stores the result, and returns it. On a `fn` error, an unexpired
+     * record is returned if present (stale-if-error), else the error rethrows.
+     */
+    wrap<T>(input: CacheKeyInput, fn: () => Promise<T>, opts?: {
+        ttlMs?: number;
+        meta?: Record<string, unknown>;
+        staleIfError?: boolean;
+    }): Promise<T>;
+    /** Hit/miss counters since creation. */
+    stats(): {
+        hits: number;
+        misses: number;
+        sets: number;
+    };
+}
+declare function createLlmCache(options?: LlmCacheOptions): LlmCache;
+
+export { type CacheGetResult, type CacheKeyInput, type CacheRecord, type CacheStore, type LlmCache, type LlmCacheOptions, type MemoryStore, contentHash, createLlmCache, memoryStore };

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+/** A stored cache record. `value` is whatever the LLM call returned (JSON-serializable). */
+interface CacheRecord<T = unknown> {
+    value: T;
+    /** Epoch ms when this expires, or null for no expiry. */
+    expiresAt: number | null;
+    /** Epoch ms when it was written. */
+    storedAt: number;
+    /** Optional metadata the caller attached (e.g. model, tokens). */
+    meta?: Record<string, unknown>;
+}
+/**
+ * A pluggable cache store. All methods may be sync or async. Implement this over
+ * Mongo, Redis, Cloudflare KV, etc. to share the cache across processes/hosts.
+ */
+interface CacheStore {
+    get(key: string): CacheRecord | null | Promise<CacheRecord | null>;
+    set(key: string, record: CacheRecord): void | Promise<void>;
+    delete(key: string): void | Promise<void>;
+}
+
+/** Stable 128-bit hex digest of a string. Deterministic across runtimes. */
+declare function contentHash(input: string): string;
+
+/**
+ * In-memory store with TTL and an LRU cap. Good for a single process; for
+ * multi-process (PM2) or cross-host sharing, pass a Mongo/Redis-backed store
+ * that implements the same {@link CacheStore} interface.
+ */
+interface MemoryStore extends CacheStore {
+    get(key: string): CacheRecord | null;
+    set(key: string, record: CacheRecord): void;
+    delete(key: string): void;
+    size(): number;
+    clear(): void;
+}
+declare function memoryStore(options?: {
+    maxEntries?: number;
+}): MemoryStore;
+
+/** The dimensions that make one LLM request identical to another. */
+interface CacheKeyInput {
+    /** The prompt / input text (or a stable stringification of your messages). */
+    input: string;
+    /** Model family — different families should not share results (e.g. "gemini", "groq-llama"). */
+    model?: string;
+    /** Bump when your prompt template changes so old results are not reused. */
+    promptVersion?: string;
+    /** Extra key parts (temperature, tools, language…) that change the output. */
+    variant?: string | Record<string, unknown>;
+}
+interface LlmCacheOptions {
+    /** Where records live. Default: in-memory LRU (1000 entries). */
+    store?: CacheStore;
+    /** Default TTL in ms. Omit or 0 for no expiry. */
+    ttlMs?: number;
+    /** Global prompt version, overridable per call. */
+    promptVersion?: string;
+    /** Namespace prefix, so multiple caches can share one store. */
+    namespace?: string;
+    /** Normalize the input before hashing. Default: trim + collapse whitespace. */
+    normalize?: (input: string) => string;
+}
+interface CacheGetResult<T> {
+    hit: boolean;
+    value: T | null;
+    key: string;
+    record: CacheRecord<T> | null;
+}
+interface LlmCache {
+    /** Compute the content-hash key for an input (no store access). */
+    key(input: CacheKeyInput): string;
+    /** Look up a cached value. */
+    get<T = unknown>(input: CacheKeyInput): Promise<CacheGetResult<T>>;
+    /** Store a value, with an optional per-call TTL and metadata. */
+    set<T = unknown>(input: CacheKeyInput, value: T, opts?: {
+        ttlMs?: number;
+        meta?: Record<string, unknown>;
+    }): Promise<void>;
+    /** Remove one entry. */
+    delete(input: CacheKeyInput): Promise<void>;
+    /**
+     * Memoize an async LLM call: returns the cached value on a hit, otherwise runs
+     * `fn`, stores the result, and returns it. On a `fn` error, an unexpired
+     * record is returned if present (stale-if-error), else the error rethrows.
+     */
+    wrap<T>(input: CacheKeyInput, fn: () => Promise<T>, opts?: {
+        ttlMs?: number;
+        meta?: Record<string, unknown>;
+        staleIfError?: boolean;
+    }): Promise<T>;
+    /** Hit/miss counters since creation. */
+    stats(): {
+        hits: number;
+        misses: number;
+        sets: number;
+    };
+}
+declare function createLlmCache(options?: LlmCacheOptions): LlmCache;
+
+export { type CacheGetResult, type CacheKeyInput, type CacheRecord, type CacheStore, type LlmCache, type LlmCacheOptions, type MemoryStore, contentHash, createLlmCache, memoryStore };

package/dist/index.js

@@ -0,0 +1,136 @@
+// src/hash.ts
+var P = 1099511628211n;
+var MASK = (1n << 64n) - 1n;
+function fnv(input, basis) {
+  let h = basis;
+  for (let i = 0; i < input.length; i++) {
+    h ^= BigInt(input.charCodeAt(i));
+    h = h * P & MASK;
+  }
+  return h;
+}
+function hex16(n) {
+  return n.toString(16).padStart(16, "0");
+}
+function contentHash(input) {
+  return hex16(fnv(input, 14695981039346656037n)) + hex16(fnv(input, 1469598103934665603n));
+}
+
+// src/stores.ts
+function memoryStore(options = {}) {
+  const max = options.maxEntries ?? 1e3;
+  const map = /* @__PURE__ */ new Map();
+  const evictExpired = (now) => {
+    for (const [k, v] of map) if (v.expiresAt !== null && v.expiresAt <= now) map.delete(k);
+  };
+  return {
+    get(key) {
+      const rec = map.get(key);
+      if (!rec) return null;
+      if (rec.expiresAt !== null && rec.expiresAt <= Date.now()) {
+        map.delete(key);
+        return null;
+      }
+      map.delete(key);
+      map.set(key, rec);
+      return rec;
+    },
+    set(key, rec) {
+      const now = Date.now();
+      evictExpired(now);
+      map.delete(key);
+      map.set(key, rec);
+      while (map.size > max) {
+        const oldest = map.keys().next().value;
+        if (oldest === void 0) break;
+        map.delete(oldest);
+      }
+    },
+    delete(key) {
+      map.delete(key);
+    },
+    size() {
+      return map.size;
+    },
+    clear() {
+      map.clear();
+    }
+  };
+}
+
+// src/index.ts
+var defaultNormalize = (s) => s.replace(/\s+/g, " ").trim();
+function variantString(v) {
+  if (v === void 0) return "";
+  if (typeof v === "string") return v;
+  return JSON.stringify(v, Object.keys(v).sort());
+}
+function createLlmCache(options = {}) {
+  const store = options.store ?? memoryStore();
+  const ns = options.namespace ?? "llm";
+  const normalize = options.normalize ?? defaultNormalize;
+  let hits = 0;
+  let misses = 0;
+  let sets = 0;
+  const key = (input) => {
+    const parts = [
+      ns,
+      input.model ?? "",
+      input.promptVersion ?? options.promptVersion ?? "",
+      variantString(input.variant),
+      normalize(input.input ?? "")
+    ].join("\0");
+    return `${ns}:${contentHash(parts)}`;
+  };
+  const get = async (input) => {
+    const k = key(input);
+    const rec = await store.get(k);
+    if (rec && (rec.expiresAt === null || rec.expiresAt > Date.now())) {
+      hits++;
+      return { hit: true, value: rec.value, key: k, record: rec };
+    }
+    misses++;
+    return { hit: false, value: null, key: k, record: null };
+  };
+  const setAt = async (k, value, ttlMs, meta) => {
+    const now = Date.now();
+    const ttl = ttlMs ?? options.ttlMs ?? 0;
+    const record = { value, storedAt: now, expiresAt: ttl > 0 ? now + ttl : null, meta };
+    await store.set(k, record);
+    sets++;
+  };
+  return {
+    key,
+    get,
+    async set(input, value, opts) {
+      await setAt(key(input), value, opts?.ttlMs, opts?.meta);
+    },
+    async delete(input) {
+      await store.delete(key(input));
+    },
+    async wrap(input, fn, opts) {
+      const k = key(input);
+      const rec = await store.get(k);
+      if (rec && (rec.expiresAt === null || rec.expiresAt > Date.now())) {
+        hits++;
+        return rec.value;
+      }
+      misses++;
+      try {
+        const value = await fn();
+        await setAt(k, value, opts?.ttlMs, opts?.meta);
+        return value;
+      } catch (err) {
+        if ((opts?.staleIfError ?? false) && rec) return rec.value;
+        throw err;
+      }
+    },
+    stats() {
+      return { hits, misses, sets };
+    }
+  };
+}
+
+export { contentHash, createLlmCache, memoryStore };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hash.ts","../src/stores.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["// A wide, dependency-free content hash. Two independent FNV-1a passes (64-bit\n// each via BigInt, different offset bases) concatenated to 32 hex chars, so the\n// collision space is ~2^128 — ample for a cache key without pulling in crypto.\nconst P = 1099511628211n;\nconst MASK = (1n << 64n) - 1n;\n\nfunction fnv(input: string, basis: bigint): bigint {\n  let h = basis;\n  for (let i = 0; i < input.length; i++) {\n    h ^= BigInt(input.charCodeAt(i));\n    h = (h * P) & MASK;\n  }\n  return h;\n}\n\nfunction hex16(n: bigint): string {\n  return n.toString(16).padStart(16, \"0\");\n}\n\n/** Stable 128-bit hex digest of a string. Deterministic across runtimes. */\nexport function contentHash(input: string): string {\n  return hex16(fnv(input, 14695981039346656037n)) + hex16(fnv(input, 1469598103934665603n));\n}\n","import type { CacheRecord, CacheStore } from \"./types.js\";\n\n/**\n * In-memory store with TTL and an LRU cap. Good for a single process; for\n * multi-process (PM2) or cross-host sharing, pass a Mongo/Redis-backed store\n * that implements the same {@link CacheStore} interface.\n */\nexport interface MemoryStore extends CacheStore {\n  get(key: string): CacheRecord | null;\n  set(key: string, record: CacheRecord): void;\n  delete(key: string): void;\n  size(): number;\n  clear(): void;\n}\n\nexport function memoryStore(options: { maxEntries?: number } = {}): MemoryStore {\n  const max = options.maxEntries ?? 1000;\n  const map = new Map<string, CacheRecord>();\n\n  const evictExpired = (now: number) => {\n    for (const [k, v] of map) if (v.expiresAt !== null && v.expiresAt <= now) map.delete(k);\n  };\n\n  return {\n    get(key) {\n      const rec = map.get(key);\n      if (!rec) return null;\n      if (rec.expiresAt !== null && rec.expiresAt <= Date.now()) {\n        map.delete(key);\n        return null;\n      }\n      // LRU touch\n      map.delete(key);\n      map.set(key, rec);\n      return rec;\n    },\n    set(key, rec) {\n      const now = Date.now();\n      evictExpired(now);\n      map.delete(key);\n      map.set(key, rec);\n      while (map.size > max) {\n        const oldest = map.keys().next().value;\n        if (oldest === undefined) break;\n        map.delete(oldest);\n      }\n    },\n    delete(key) {\n      map.delete(key);\n    },\n    size() {\n      return map.size;\n    },\n    clear() {\n      map.clear();\n    },\n  };\n}\n","import { contentHash } from \"./hash.js\";\nimport { memoryStore } from \"./stores.js\";\nimport type { CacheRecord, CacheStore } from \"./types.js\";\n\nexport { contentHash } from \"./hash.js\";\nexport { memoryStore } from \"./stores.js\";\nexport type { MemoryStore } from \"./stores.js\";\nexport type { CacheRecord, CacheStore } from \"./types.js\";\n\n/** The dimensions that make one LLM request identical to another. */\nexport interface CacheKeyInput {\n  /** The prompt / input text (or a stable stringification of your messages). */\n  input: string;\n  /** Model family — different families should not share results (e.g. \"gemini\", \"groq-llama\"). */\n  model?: string;\n  /** Bump when your prompt template changes so old results are not reused. */\n  promptVersion?: string;\n  /** Extra key parts (temperature, tools, language…) that change the output. */\n  variant?: string | Record<string, unknown>;\n}\n\nexport interface LlmCacheOptions {\n  /** Where records live. Default: in-memory LRU (1000 entries). */\n  store?: CacheStore;\n  /** Default TTL in ms. Omit or 0 for no expiry. */\n  ttlMs?: number;\n  /** Global prompt version, overridable per call. */\n  promptVersion?: string;\n  /** Namespace prefix, so multiple caches can share one store. */\n  namespace?: string;\n  /** Normalize the input before hashing. Default: trim + collapse whitespace. */\n  normalize?: (input: string) => string;\n}\n\nexport interface CacheGetResult<T> {\n  hit: boolean;\n  value: T | null;\n  key: string;\n  record: CacheRecord<T> | null;\n}\n\nexport interface LlmCache {\n  /** Compute the content-hash key for an input (no store access). */\n  key(input: CacheKeyInput): string;\n  /** Look up a cached value. */\n  get<T = unknown>(input: CacheKeyInput): Promise<CacheGetResult<T>>;\n  /** Store a value, with an optional per-call TTL and metadata. */\n  set<T = unknown>(input: CacheKeyInput, value: T, opts?: { ttlMs?: number; meta?: Record<string, unknown> }): Promise<void>;\n  /** Remove one entry. */\n  delete(input: CacheKeyInput): Promise<void>;\n  /**\n   * Memoize an async LLM call: returns the cached value on a hit, otherwise runs\n   * `fn`, stores the result, and returns it. On a `fn` error, an unexpired\n   * record is returned if present (stale-if-error), else the error rethrows.\n   */\n  wrap<T>(input: CacheKeyInput, fn: () => Promise<T>, opts?: { ttlMs?: number; meta?: Record<string, unknown>; staleIfError?: boolean }): Promise<T>;\n  /** Hit/miss counters since creation. */\n  stats(): { hits: number; misses: number; sets: number };\n}\n\nconst defaultNormalize = (s: string): string => s.replace(/\\s+/g, \" \").trim();\n\nfunction variantString(v: CacheKeyInput[\"variant\"]): string {\n  if (v === undefined) return \"\";\n  if (typeof v === \"string\") return v;\n  // Stable stringify: sort keys.\n  return JSON.stringify(v, Object.keys(v).sort());\n}\n\nexport function createLlmCache(options: LlmCacheOptions = {}): LlmCache {\n  const store = options.store ?? memoryStore();\n  const ns = options.namespace ?? \"llm\";\n  const normalize = options.normalize ?? defaultNormalize;\n  let hits = 0;\n  let misses = 0;\n  let sets = 0;\n\n  const key = (input: CacheKeyInput): string => {\n    const parts = [\n      ns,\n      input.model ?? \"\",\n      input.promptVersion ?? options.promptVersion ?? \"\",\n      variantString(input.variant),\n      normalize(input.input ?? \"\"),\n    ].join(\"\\u0000\");\n    return `${ns}:${contentHash(parts)}`;\n  };\n\n  const get = async <T>(input: CacheKeyInput): Promise<CacheGetResult<T>> => {\n    const k = key(input);\n    const rec = (await store.get(k)) as CacheRecord<T> | null;\n    if (rec && (rec.expiresAt === null || rec.expiresAt > Date.now())) {\n      hits++;\n      return { hit: true, value: rec.value, key: k, record: rec };\n    }\n    misses++;\n    return { hit: false, value: null, key: k, record: null };\n  };\n\n  const setAt = async <T>(k: string, value: T, ttlMs: number | undefined, meta?: Record<string, unknown>): Promise<void> => {\n    const now = Date.now();\n    const ttl = ttlMs ?? options.ttlMs ?? 0;\n    const record: CacheRecord<T> = { value, storedAt: now, expiresAt: ttl > 0 ? now + ttl : null, meta };\n    await store.set(k, record as CacheRecord);\n    sets++;\n  };\n\n  return {\n    key,\n    get,\n    async set(input, value, opts) {\n      await setAt(key(input), value, opts?.ttlMs, opts?.meta);\n    },\n    async delete(input) {\n      await store.delete(key(input));\n    },\n    async wrap(input, fn, opts) {\n      const k = key(input);\n      const rec = (await store.get(k)) as CacheRecord | null;\n      if (rec && (rec.expiresAt === null || rec.expiresAt > Date.now())) {\n        hits++;\n        return rec.value as Awaited<ReturnType<typeof fn>>;\n      }\n      misses++;\n      try {\n        const value = await fn();\n        await setAt(k, value, opts?.ttlMs, opts?.meta);\n        return value;\n      } catch (err) {\n        if ((opts?.staleIfError ?? false) && rec) return rec.value as Awaited<ReturnType<typeof fn>>;\n        throw err;\n      }\n    },\n    stats() {\n      return { hits, misses, sets };\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@lacspace/llm-cache",
+  "version": "1.0.0",
+  "description": "A content-hash cache for LLM calls — key by (model family, prompt version, normalized input) so identical requests, retries after a 429, and repeated rewrites never pay twice. Pluggable async store (in-memory LRU built in, Mongo/Redis/KV via a tiny adapter interface), TTL, stale-if-error, and a wrap() memoizer. Zero-dependency, isomorphic, typed.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "scripts": { "build": "tsup", "prepublishOnly": "npm run build" },
+  "keywords": ["llm-cache", "cache", "memoize", "content-hash", "prompt-cache", "ttl", "lru", "openai", "gemini", "groq", "rate-limit", "429", "zero-dependency", "isomorphic", "typescript"],
+  "author": "Lacspace <contact@lacspace.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://developer.lacspace.com/packages/llm-cache",
+  "repository": { "type": "git", "url": "git+https://github.com/lacspace/npm-packages.git", "directory": "llm-cache" },
+  "bugs": { "url": "https://github.com/lacspace/npm-packages/issues" },
+  "engines": { "node": ">=18" },
+  "publishConfig": { "access": "public" }
+}