@nodellmcache/core 0.1.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @nodellmcache/core
+
+## 1.1.0
+
+### Minor Changes
+
+- Add stale-while-revalidate to `BaseCacheManager` via `getOrRevalidate(input, generator, { ttl, staleTtl })`: a stale-but-unexpired entry is served immediately while a fresh value is fetched in the background, with concurrent stale hits coalesced into a single refresh. Adds `staleAt` to `CacheMetadata` and `staleTtl` to `CacheOptions`.
+- Add request coalescing (singleflight): concurrent misses for the same key run the generator once instead of N times. Applies to both `getOrGenerate` and `getOrRevalidate`. Inherited by every cache manager.
+
+## 1.0.0
+
+### Minor Changes
+
+- a2633d8: Initial release of `@nodellmcache/core`: shared interfaces and types (`StorageAdapter`, `VectorStoreAdapter`, `CompressionEngine`, `CacheEntry`, `MetricsSink`, `CacheType`, `LLMProvider`, `CompressionAlgo`), the `KeyBuilder`, `TTLManager`, `JsonSerializer`, the `BaseCacheManager` cache-aside base class, and the typed error hierarchy. Zero external dependencies.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NodeLLMCache contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation 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 following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

package/dist/index.cjs

@@ -143,6 +143,10 @@ var BaseCacheManager = class {
   metrics;
   hits = 0;
   misses = 0;
+  /** Keys with an in-flight background revalidation, to avoid duplicate refreshes. */
+  refreshing = /* @__PURE__ */ new Set();
+  /** In-flight generations, so concurrent misses for the same key run the generator once. */
+  inflight = /* @__PURE__ */ new Map();
   constructor(options) {
     this.adapter = options.adapter;
     this.defaultTTL = options.defaultTTL;
@@ -166,6 +170,7 @@ var BaseCacheManager = class {
   buildEntry(key, value, options) {
     const createdAt = Date.now();
     const ttl = options?.ttl ?? this.defaultTTL;
+    const staleTtl = options?.staleTtl;
     return {
       key,
       value,
@@ -177,7 +182,8 @@ var BaseCacheManager = class {
         cacheType: this.cacheType,
         provider: options?.provider,
         model: options?.model,
-        tokenCount: options?.tokenCount
+        tokenCount: options?.tokenCount,
+        staleAt: staleTtl !== void 0 && staleTtl > 0 ? createdAt + staleTtl : void 0
       }
     };
   }
@@ -211,17 +217,46 @@ var BaseCacheManager = class {
       provider: options?.provider,
       model: options?.model
     });
-    const value = await generator();
-    const ttl = options?.ttl ?? this.defaultTTL;
-    const entry = this.buildEntry(key, value, options);
-    await this.adapter.set(key, entry, ttl);
-    this.metrics.emit("cache.set", {
+    return this.coalescedGenerate(key, generator, options, start);
+  }
+  /**
+   * Stale-while-revalidate read-through. Like {@link getOrGenerate}, but when a
+   * cached entry is *stale* (past its `staleTtl`/`staleAt` but not yet expired)
+   * it is returned immediately and a fresh value is fetched in the background.
+   * Concurrent stale hits for the same key trigger at most one background
+   * refresh. A failed background refresh is swallowed and the stale value stands
+   * until it fully expires.
+   */
+  async getOrRevalidate(input, generator, options) {
+    if (options?.cache === false) {
+      return generator();
+    }
+    const key = this.buildKey(input, options);
+    const start = Date.now();
+    const cached = await this.adapter.get(key);
+    if (cached && !TTLManager.isExpired(cached)) {
+      this.hits++;
+      this.metrics.emit("cache.hit", {
+        cacheType: this.cacheType,
+        latencyMs: Date.now() - start,
+        tokensSaved: cached.metadata.tokenCount,
+        provider: options?.provider,
+        model: options?.model
+      });
+      const staleAt = cached.metadata.staleAt;
+      if (staleAt !== void 0 && staleAt <= Date.now()) {
+        this.revalidate(key, generator, options);
+      }
+      return cached.value;
+    }
+    this.misses++;
+    this.metrics.emit("cache.miss", {
       cacheType: this.cacheType,
       latencyMs: Date.now() - start,
       provider: options?.provider,
       model: options?.model
     });
-    return value;
+    return this.coalescedGenerate(key, generator, options, start);
   }
   /**
    * Removes a single entry by its input (and namespacing options).
@@ -242,6 +277,49 @@ var BaseCacheManager = class {
       entryCount: adapterStats.entryCount
     };
   }
+  /**
+   * Runs the generator and persists the result, deduplicating concurrent calls
+   * for the same key (singleflight): while one generation is in flight, other
+   * callers join it instead of invoking the generator again. Prevents a
+   * thundering herd of identical API calls on a cold key.
+   */
+  coalescedGenerate(key, generator, options, start) {
+    const existing = this.inflight.get(key);
+    if (existing) return existing;
+    const promise = (async () => {
+      const value = await generator();
+      await this.persist(key, value, options, start);
+      return value;
+    })();
+    this.inflight.set(key, promise);
+    return promise.finally(() => this.inflight.delete(key));
+  }
+  /** Builds an entry, writes it through the adapter, and emits `cache.set`. */
+  async persist(key, value, options, start) {
+    const ttl = options?.ttl ?? this.defaultTTL;
+    const entry = this.buildEntry(key, value, options);
+    await this.adapter.set(key, entry, ttl);
+    this.metrics.emit("cache.set", {
+      cacheType: this.cacheType,
+      latencyMs: Date.now() - start,
+      provider: options?.provider,
+      model: options?.model
+    });
+  }
+  /** Fire-and-forget background refresh for a stale entry, coalesced per key. */
+  revalidate(key, generator, options) {
+    if (this.refreshing.has(key)) return;
+    this.refreshing.add(key);
+    void (async () => {
+      try {
+        const value = await generator();
+        await this.persist(key, value, options, Date.now());
+      } catch {
+      } finally {
+        this.refreshing.delete(key);
+      }
+    })();
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/KeyBuilder.ts","../src/TTLManager.ts","../src/Serializer.ts","../src/BaseCacheManager.ts"],"sourcesContent":["export * from './types.js'\nexport * from './interfaces.js'\nexport * from './errors.js'\nexport { KeyBuilder } from './KeyBuilder.js'\nexport { TTLManager } from './TTLManager.js'\nexport { type Serializer, JsonSerializer } from './Serializer.js'\nexport {\n  BaseCacheManager,\n  noopMetrics,\n  type BaseCacheManagerOptions,\n} from './BaseCacheManager.js'\n","/**\n * Base class for every error thrown by NodeLLMCache packages. Catching this\n * catches anything the library throws intentionally.\n */\nexport class NodeLLMCacheError extends Error {\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options)\n    this.name = new.target.name\n    // Restore prototype chain for instanceof across the ES5 transpile boundary.\n    Object.setPrototypeOf(this, new.target.prototype)\n  }\n}\n\n/** Thrown when a storage adapter operation fails. */\nexport class CacheAdapterError extends NodeLLMCacheError {}\n\n/** Thrown when compression or decompression fails. */\nexport class CompressionError extends NodeLLMCacheError {}\n\n/** Thrown when serialization or deserialization fails. */\nexport class SerializationError extends NodeLLMCacheError {}\n\n/** Thrown when a value fails validation (e.g. malformed configuration). */\nexport class ValidationError extends NodeLLMCacheError {}\n","import { createHash } from 'node:crypto'\nimport type { CacheType, LLMProvider } from './types.js'\n\n/**\n * Builds deterministic, collision-resistant cache keys.\n *\n * Format: `{type}:{provider}:{model}:{sha256-hash}`\n *\n * The raw input text is normalized and hashed with SHA-256 — keys never\n * contain raw prompt text, which keeps sensitive content out of storage keys\n * and logs.\n */\nexport class KeyBuilder {\n  /**\n   * Normalizes text before hashing so trivially different inputs collapse to\n   * the same key: trims surrounding whitespace, lowercases, and collapses any\n   * run of whitespace to a single space.\n   */\n  static normalize(text: string): string {\n    return text.trim().toLowerCase().replace(/\\s+/g, ' ')\n  }\n\n  /**\n   * Produces the SHA-256 hex digest of the normalized text.\n   */\n  static hash(text: string): string {\n    return createHash('sha256').update(KeyBuilder.normalize(text)).digest('hex')\n  }\n\n  /**\n   * Builds a fully namespaced cache key.\n   *\n   * @example\n   * KeyBuilder.build('prompt', 'openai', 'gpt-4o', 'hello world')\n   * // 'prompt:openai:gpt-4o:b94d27b9...'\n   */\n  static build(\n    type: CacheType,\n    provider: LLMProvider | string,\n    model: string,\n    text: string,\n  ): string {\n    return `${type}:${provider}:${model}:${KeyBuilder.hash(text)}`\n  }\n}\n","import type { CacheEntry } from './interfaces.js'\n\n/**\n * Centralizes time-to-live arithmetic: computing expiry timestamps, checking\n * expiry, and supporting sliding-window refresh. All durations are relative\n * milliseconds; all timestamps are absolute epoch milliseconds.\n */\nexport class TTLManager {\n  /**\n   * Computes the absolute expiry timestamp for an entry created at `createdAt`\n   * with a relative `ttl`. Returns `undefined` when `ttl` is not a positive\n   * number, meaning the entry never expires.\n   */\n  static computeExpiresAt(createdAt: number, ttl?: number): number | undefined {\n    if (ttl === undefined || ttl <= 0) return undefined\n    return createdAt + ttl\n  }\n\n  /**\n   * Returns true when the entry has an expiry and that expiry is at or before\n   * `now` (defaults to the current time).\n   */\n  static isExpired(entry: Pick<CacheEntry<unknown>, 'expiresAt'>, now: number = Date.now()): boolean {\n    return entry.expiresAt !== undefined && entry.expiresAt <= now\n  }\n\n  /**\n   * Milliseconds remaining until the entry expires. Returns `Infinity` for\n   * entries with no expiry, and `0` for already-expired entries.\n   */\n  static remaining(entry: Pick<CacheEntry<unknown>, 'expiresAt'>, now: number = Date.now()): number {\n    if (entry.expiresAt === undefined) return Infinity\n    return Math.max(0, entry.expiresAt - now)\n  }\n\n  /**\n   * Computes a refreshed expiry for a sliding-window TTL: extends the entry's\n   * life by `ttl` from `now`. Returns `undefined` when `ttl` is not positive.\n   */\n  static slide(ttl?: number, now: number = Date.now()): number | undefined {\n    return TTLManager.computeExpiresAt(now, ttl)\n  }\n}\n","import { SerializationError } from './errors.js'\n\n/**\n * Converts values to and from `Buffer` for storage. Implementations decide the\n * wire format.\n *\n * The architecture calls for MessagePack as the primary format, but\n * `@nodellmcache/core` must stay dependency-free, so it ships only the JSON\n * implementation below. A MessagePack serializer can be supplied by an optional\n * package and injected wherever a `Serializer` is accepted.\n */\nexport interface Serializer {\n  serialize<T>(value: T): Buffer\n  deserialize<T>(data: Buffer): T\n}\n\n/**\n * Default JSON-backed serializer. Zero dependencies; handles the common case\n * and wraps failures in {@link SerializationError}.\n */\nexport class JsonSerializer implements Serializer {\n  serialize<T>(value: T): Buffer {\n    try {\n      return Buffer.from(JSON.stringify(value), 'utf8')\n    } catch (cause) {\n      throw new SerializationError('Failed to serialize value to JSON', { cause })\n    }\n  }\n\n  deserialize<T>(data: Buffer): T {\n    try {\n      return JSON.parse(data.toString('utf8')) as T\n    } catch (cause) {\n      throw new SerializationError('Failed to deserialize JSON value', { cause })\n    }\n  }\n}\n","import { KeyBuilder } from './KeyBuilder.js'\nimport { TTLManager } from './TTLManager.js'\nimport type {\n  CacheEntry,\n  CacheOptions,\n  CacheStats,\n  MetricsSink,\n  StorageAdapter,\n} from './interfaces.js'\nimport type { CacheType } from './types.js'\n\n/** A metrics sink that discards everything; the default when none is injected. */\nexport const noopMetrics: MetricsSink = {\n  emit() {\n    // intentionally empty\n  },\n}\n\n/**\n * Construction options shared by all cache managers.\n */\nexport interface BaseCacheManagerOptions<T> {\n  adapter: StorageAdapter<T>\n  /** Default relative TTL in milliseconds applied to entries lacking their own. */\n  defaultTTL?: number\n  /** Metrics sink; defaults to a no-op so core stays dependency-free. */\n  metrics?: MetricsSink\n}\n\n/**\n * Shared base for every feature cache (prompt, embedding, semantic, ...).\n *\n * Provides the cache-aside `getOrGenerate` flow, key building, entry\n * construction, invalidation, and hit/miss accounting. Subclasses declare their\n * {@link CacheType} and may override {@link buildKey} for custom namespacing.\n */\nexport abstract class BaseCacheManager<T> {\n  /** The workload category for keys and metrics. */\n  protected abstract readonly cacheType: CacheType\n\n  protected readonly adapter: StorageAdapter<T>\n  protected readonly defaultTTL: number | undefined\n  protected readonly metrics: MetricsSink\n\n  private hits = 0\n  private misses = 0\n\n  constructor(options: BaseCacheManagerOptions<T>) {\n    this.adapter = options.adapter\n    this.defaultTTL = options.defaultTTL\n    this.metrics = options.metrics ?? noopMetrics\n  }\n\n  /**\n   * Builds the storage key for an input. Defaults to the canonical\n   * `{type}:{provider}:{model}:{hash}` format via {@link KeyBuilder}.\n   */\n  protected buildKey(input: string, options?: CacheOptions): string {\n    return KeyBuilder.build(\n      this.cacheType,\n      options?.provider ?? 'unknown',\n      options?.model ?? 'default',\n      input,\n    )\n  }\n\n  /**\n   * Wraps a value in a {@link CacheEntry} with computed expiry and metadata.\n   */\n  protected buildEntry(key: string, value: T, options?: CacheOptions): CacheEntry<T> {\n    const createdAt = Date.now()\n    const ttl = options?.ttl ?? this.defaultTTL\n    return {\n      key,\n      value,\n      createdAt,\n      expiresAt: TTLManager.computeExpiresAt(createdAt, ttl),\n      metadata: {\n        compressed: false,\n        originalSize: 0,\n        cacheType: this.cacheType,\n        provider: options?.provider,\n        model: options?.model,\n        tokenCount: options?.tokenCount,\n      },\n    }\n  }\n\n  /**\n   * Cache-aside read-through. Returns the cached value on a hit, otherwise\n   * invokes `generator`, stores the result, and returns it. Set\n   * `options.cache = false` to bypass the cache for both read and write.\n   */\n  async getOrGenerate(\n    input: string,\n    generator: () => Promise<T>,\n    options?: CacheOptions,\n  ): Promise<T> {\n    // A deliberate bypass is neither a hit nor a miss — skip the cache and\n    // metrics entirely so accounting reflects only real cache consultations.\n    if (options?.cache === false) {\n      return generator()\n    }\n\n    const key = this.buildKey(input, options)\n    const start = Date.now()\n\n    const cached = await this.adapter.get(key)\n    if (cached && !TTLManager.isExpired(cached)) {\n      this.hits++\n      this.metrics.emit('cache.hit', {\n        cacheType: this.cacheType,\n        latencyMs: Date.now() - start,\n        tokensSaved: cached.metadata.tokenCount,\n        provider: options?.provider,\n        model: options?.model,\n      })\n      return cached.value\n    }\n\n    this.misses++\n    this.metrics.emit('cache.miss', {\n      cacheType: this.cacheType,\n      latencyMs: Date.now() - start,\n      provider: options?.provider,\n      model: options?.model,\n    })\n\n    const value = await generator()\n\n    const ttl = options?.ttl ?? this.defaultTTL\n    const entry = this.buildEntry(key, value, options)\n    await this.adapter.set(key, entry, ttl)\n    this.metrics.emit('cache.set', {\n      cacheType: this.cacheType,\n      latencyMs: Date.now() - start,\n      provider: options?.provider,\n      model: options?.model,\n    })\n\n    return value\n  }\n\n  /**\n   * Removes a single entry by its input (and namespacing options).\n   */\n  async invalidate(input: string, options?: CacheOptions): Promise<void> {\n    await this.adapter.delete(this.buildKey(input, options))\n  }\n\n  /**\n   * Returns hit/miss accounting for this manager plus the adapter's entry count.\n   */\n  async stats(): Promise<CacheStats> {\n    const total = this.hits + this.misses\n    const adapterStats = await this.adapter.stats()\n    return {\n      hits: this.hits,\n      misses: this.misses,\n      hitRate: total === 0 ? 0 : this.hits / total,\n      entryCount: adapterStats.entryCount,\n    }\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/KeyBuilder.ts","../src/TTLManager.ts","../src/Serializer.ts","../src/BaseCacheManager.ts"],"sourcesContent":["export * from './types.js'\nexport * from './interfaces.js'\nexport * from './errors.js'\nexport { KeyBuilder } from './KeyBuilder.js'\nexport { TTLManager } from './TTLManager.js'\nexport { type Serializer, JsonSerializer } from './Serializer.js'\nexport {\n  BaseCacheManager,\n  noopMetrics,\n  type BaseCacheManagerOptions,\n} from './BaseCacheManager.js'\n","/**\n * Base class for every error thrown by NodeLLMCache packages. Catching this\n * catches anything the library throws intentionally.\n */\nexport class NodeLLMCacheError extends Error {\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options)\n    this.name = new.target.name\n    // Restore prototype chain for instanceof across the ES5 transpile boundary.\n    Object.setPrototypeOf(this, new.target.prototype)\n  }\n}\n\n/** Thrown when a storage adapter operation fails. */\nexport class CacheAdapterError extends NodeLLMCacheError {}\n\n/** Thrown when compression or decompression fails. */\nexport class CompressionError extends NodeLLMCacheError {}\n\n/** Thrown when serialization or deserialization fails. */\nexport class SerializationError extends NodeLLMCacheError {}\n\n/** Thrown when a value fails validation (e.g. malformed configuration). */\nexport class ValidationError extends NodeLLMCacheError {}\n","import { createHash } from 'node:crypto'\nimport type { CacheType, LLMProvider } from './types.js'\n\n/**\n * Builds deterministic, collision-resistant cache keys.\n *\n * Format: `{type}:{provider}:{model}:{sha256-hash}`\n *\n * The raw input text is normalized and hashed with SHA-256 — keys never\n * contain raw prompt text, which keeps sensitive content out of storage keys\n * and logs.\n */\nexport class KeyBuilder {\n  /**\n   * Normalizes text before hashing so trivially different inputs collapse to\n   * the same key: trims surrounding whitespace, lowercases, and collapses any\n   * run of whitespace to a single space.\n   */\n  static normalize(text: string): string {\n    return text.trim().toLowerCase().replace(/\\s+/g, ' ')\n  }\n\n  /**\n   * Produces the SHA-256 hex digest of the normalized text.\n   */\n  static hash(text: string): string {\n    return createHash('sha256').update(KeyBuilder.normalize(text)).digest('hex')\n  }\n\n  /**\n   * Builds a fully namespaced cache key.\n   *\n   * @example\n   * KeyBuilder.build('prompt', 'openai', 'gpt-4o', 'hello world')\n   * // 'prompt:openai:gpt-4o:b94d27b9...'\n   */\n  static build(\n    type: CacheType,\n    provider: LLMProvider | string,\n    model: string,\n    text: string,\n  ): string {\n    return `${type}:${provider}:${model}:${KeyBuilder.hash(text)}`\n  }\n}\n","import type { CacheEntry } from './interfaces.js'\n\n/**\n * Centralizes time-to-live arithmetic: computing expiry timestamps, checking\n * expiry, and supporting sliding-window refresh. All durations are relative\n * milliseconds; all timestamps are absolute epoch milliseconds.\n */\nexport class TTLManager {\n  /**\n   * Computes the absolute expiry timestamp for an entry created at `createdAt`\n   * with a relative `ttl`. Returns `undefined` when `ttl` is not a positive\n   * number, meaning the entry never expires.\n   */\n  static computeExpiresAt(createdAt: number, ttl?: number): number | undefined {\n    if (ttl === undefined || ttl <= 0) return undefined\n    return createdAt + ttl\n  }\n\n  /**\n   * Returns true when the entry has an expiry and that expiry is at or before\n   * `now` (defaults to the current time).\n   */\n  static isExpired(entry: Pick<CacheEntry<unknown>, 'expiresAt'>, now: number = Date.now()): boolean {\n    return entry.expiresAt !== undefined && entry.expiresAt <= now\n  }\n\n  /**\n   * Milliseconds remaining until the entry expires. Returns `Infinity` for\n   * entries with no expiry, and `0` for already-expired entries.\n   */\n  static remaining(entry: Pick<CacheEntry<unknown>, 'expiresAt'>, now: number = Date.now()): number {\n    if (entry.expiresAt === undefined) return Infinity\n    return Math.max(0, entry.expiresAt - now)\n  }\n\n  /**\n   * Computes a refreshed expiry for a sliding-window TTL: extends the entry's\n   * life by `ttl` from `now`. Returns `undefined` when `ttl` is not positive.\n   */\n  static slide(ttl?: number, now: number = Date.now()): number | undefined {\n    return TTLManager.computeExpiresAt(now, ttl)\n  }\n}\n","import { SerializationError } from './errors.js'\n\n/**\n * Converts values to and from `Buffer` for storage. Implementations decide the\n * wire format.\n *\n * The architecture calls for MessagePack as the primary format, but\n * `@nodellmcache/core` must stay dependency-free, so it ships only the JSON\n * implementation below. A MessagePack serializer can be supplied by an optional\n * package and injected wherever a `Serializer` is accepted.\n */\nexport interface Serializer {\n  serialize<T>(value: T): Buffer\n  deserialize<T>(data: Buffer): T\n}\n\n/**\n * Default JSON-backed serializer. Zero dependencies; handles the common case\n * and wraps failures in {@link SerializationError}.\n */\nexport class JsonSerializer implements Serializer {\n  serialize<T>(value: T): Buffer {\n    try {\n      return Buffer.from(JSON.stringify(value), 'utf8')\n    } catch (cause) {\n      throw new SerializationError('Failed to serialize value to JSON', { cause })\n    }\n  }\n\n  deserialize<T>(data: Buffer): T {\n    try {\n      return JSON.parse(data.toString('utf8')) as T\n    } catch (cause) {\n      throw new SerializationError('Failed to deserialize JSON value', { cause })\n    }\n  }\n}\n","import { KeyBuilder } from './KeyBuilder.js'\nimport { TTLManager } from './TTLManager.js'\nimport type {\n  CacheEntry,\n  CacheOptions,\n  CacheStats,\n  MetricsSink,\n  StorageAdapter,\n} from './interfaces.js'\nimport type { CacheType } from './types.js'\n\n/** A metrics sink that discards everything; the default when none is injected. */\nexport const noopMetrics: MetricsSink = {\n  emit() {\n    // intentionally empty\n  },\n}\n\n/**\n * Construction options shared by all cache managers.\n */\nexport interface BaseCacheManagerOptions<T> {\n  adapter: StorageAdapter<T>\n  /** Default relative TTL in milliseconds applied to entries lacking their own. */\n  defaultTTL?: number\n  /** Metrics sink; defaults to a no-op so core stays dependency-free. */\n  metrics?: MetricsSink\n}\n\n/**\n * Shared base for every feature cache (prompt, embedding, semantic, ...).\n *\n * Provides the cache-aside `getOrGenerate` flow, key building, entry\n * construction, invalidation, and hit/miss accounting. Subclasses declare their\n * {@link CacheType} and may override {@link buildKey} for custom namespacing.\n */\nexport abstract class BaseCacheManager<T> {\n  /** The workload category for keys and metrics. */\n  protected abstract readonly cacheType: CacheType\n\n  protected readonly adapter: StorageAdapter<T>\n  protected readonly defaultTTL: number | undefined\n  protected readonly metrics: MetricsSink\n\n  private hits = 0\n  private misses = 0\n  /** Keys with an in-flight background revalidation, to avoid duplicate refreshes. */\n  private readonly refreshing = new Set<string>()\n  /** In-flight generations, so concurrent misses for the same key run the generator once. */\n  private readonly inflight = new Map<string, Promise<T>>()\n\n  constructor(options: BaseCacheManagerOptions<T>) {\n    this.adapter = options.adapter\n    this.defaultTTL = options.defaultTTL\n    this.metrics = options.metrics ?? noopMetrics\n  }\n\n  /**\n   * Builds the storage key for an input. Defaults to the canonical\n   * `{type}:{provider}:{model}:{hash}` format via {@link KeyBuilder}.\n   */\n  protected buildKey(input: string, options?: CacheOptions): string {\n    return KeyBuilder.build(\n      this.cacheType,\n      options?.provider ?? 'unknown',\n      options?.model ?? 'default',\n      input,\n    )\n  }\n\n  /**\n   * Wraps a value in a {@link CacheEntry} with computed expiry and metadata.\n   */\n  protected buildEntry(key: string, value: T, options?: CacheOptions): CacheEntry<T> {\n    const createdAt = Date.now()\n    const ttl = options?.ttl ?? this.defaultTTL\n    const staleTtl = options?.staleTtl\n    return {\n      key,\n      value,\n      createdAt,\n      expiresAt: TTLManager.computeExpiresAt(createdAt, ttl),\n      metadata: {\n        compressed: false,\n        originalSize: 0,\n        cacheType: this.cacheType,\n        provider: options?.provider,\n        model: options?.model,\n        tokenCount: options?.tokenCount,\n        staleAt:\n          staleTtl !== undefined && staleTtl > 0 ? createdAt + staleTtl : undefined,\n      },\n    }\n  }\n\n  /**\n   * Cache-aside read-through. Returns the cached value on a hit, otherwise\n   * invokes `generator`, stores the result, and returns it. Set\n   * `options.cache = false` to bypass the cache for both read and write.\n   */\n  async getOrGenerate(\n    input: string,\n    generator: () => Promise<T>,\n    options?: CacheOptions,\n  ): Promise<T> {\n    // A deliberate bypass is neither a hit nor a miss — skip the cache and\n    // metrics entirely so accounting reflects only real cache consultations.\n    if (options?.cache === false) {\n      return generator()\n    }\n\n    const key = this.buildKey(input, options)\n    const start = Date.now()\n\n    const cached = await this.adapter.get(key)\n    if (cached && !TTLManager.isExpired(cached)) {\n      this.hits++\n      this.metrics.emit('cache.hit', {\n        cacheType: this.cacheType,\n        latencyMs: Date.now() - start,\n        tokensSaved: cached.metadata.tokenCount,\n        provider: options?.provider,\n        model: options?.model,\n      })\n      return cached.value\n    }\n\n    this.misses++\n    this.metrics.emit('cache.miss', {\n      cacheType: this.cacheType,\n      latencyMs: Date.now() - start,\n      provider: options?.provider,\n      model: options?.model,\n    })\n\n    return this.coalescedGenerate(key, generator, options, start)\n  }\n\n  /**\n   * Stale-while-revalidate read-through. Like {@link getOrGenerate}, but when a\n   * cached entry is *stale* (past its `staleTtl`/`staleAt` but not yet expired)\n   * it is returned immediately and a fresh value is fetched in the background.\n   * Concurrent stale hits for the same key trigger at most one background\n   * refresh. A failed background refresh is swallowed and the stale value stands\n   * until it fully expires.\n   */\n  async getOrRevalidate(\n    input: string,\n    generator: () => Promise<T>,\n    options?: CacheOptions,\n  ): Promise<T> {\n    if (options?.cache === false) {\n      return generator()\n    }\n\n    const key = this.buildKey(input, options)\n    const start = Date.now()\n\n    const cached = await this.adapter.get(key)\n    if (cached && !TTLManager.isExpired(cached)) {\n      this.hits++\n      this.metrics.emit('cache.hit', {\n        cacheType: this.cacheType,\n        latencyMs: Date.now() - start,\n        tokensSaved: cached.metadata.tokenCount,\n        provider: options?.provider,\n        model: options?.model,\n      })\n      const staleAt = cached.metadata.staleAt\n      if (staleAt !== undefined && staleAt <= Date.now()) {\n        this.revalidate(key, generator, options)\n      }\n      return cached.value\n    }\n\n    this.misses++\n    this.metrics.emit('cache.miss', {\n      cacheType: this.cacheType,\n      latencyMs: Date.now() - start,\n      provider: options?.provider,\n      model: options?.model,\n    })\n\n    return this.coalescedGenerate(key, generator, options, start)\n  }\n\n  /**\n   * Removes a single entry by its input (and namespacing options).\n   */\n  async invalidate(input: string, options?: CacheOptions): Promise<void> {\n    await this.adapter.delete(this.buildKey(input, options))\n  }\n\n  /**\n   * Returns hit/miss accounting for this manager plus the adapter's entry count.\n   */\n  async stats(): Promise<CacheStats> {\n    const total = this.hits + this.misses\n    const adapterStats = await this.adapter.stats()\n    return {\n      hits: this.hits,\n      misses: this.misses,\n      hitRate: total === 0 ? 0 : this.hits / total,\n      entryCount: adapterStats.entryCount,\n    }\n  }\n\n  /**\n   * Runs the generator and persists the result, deduplicating concurrent calls\n   * for the same key (singleflight): while one generation is in flight, other\n   * callers join it instead of invoking the generator again. Prevents a\n   * thundering herd of identical API calls on a cold key.\n   */\n  private coalescedGenerate(\n    key: string,\n    generator: () => Promise<T>,\n    options: CacheOptions | undefined,\n    start: number,\n  ): Promise<T> {\n    const existing = this.inflight.get(key)\n    if (existing) return existing\n\n    const promise = (async () => {\n      const value = await generator()\n      await this.persist(key, value, options, start)\n      return value\n    })()\n    this.inflight.set(key, promise)\n    return promise.finally(() => this.inflight.delete(key))\n  }\n\n  /** Builds an entry, writes it through the adapter, and emits `cache.set`. */\n  private async persist(\n    key: string,\n    value: T,\n    options: CacheOptions | undefined,\n    start: number,\n  ): Promise<void> {\n    const ttl = options?.ttl ?? this.defaultTTL\n    const entry = this.buildEntry(key, value, options)\n    await this.adapter.set(key, entry, ttl)\n    this.metrics.emit('cache.set', {\n      cacheType: this.cacheType,\n      latencyMs: Date.now() - start,\n      provider: options?.provider,\n      model: options?.model,\n    })\n  }\n\n  /** Fire-and-forget background refresh for a stale entry, coalesced per key. */\n  private revalidate(key: string, generator: () => Promise<T>, options?: CacheOptions): void {\n    if (this.refreshing.has(key)) return\n    this.refreshing.add(key)\n    void (async () => {\n      try {\n        const value = await generator()\n        await this.persist(key, value, options, Date.now())\n      } catch {\n        // Swallow background-refresh failures: the stale value stands until expiry.\n      } finally {\n        this.refreshing.delete(key)\n      }\n    })()\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -32,6 +32,13 @@ interface CacheMetadata {
     provider?: LLMProvider;
     model?: string;
     tokenCount?: number;
+    /**
+     * Absolute epoch ms after which the entry is considered *stale* but still
+     * usable. Used by stale-while-revalidate: a stale hit is served immediately
+     * while a fresh value is fetched in the background. Always earlier than
+     * `expiresAt`.
+     */
+    staleAt?: number;
 }
 /**
  * A single cached value with its bookkeeping. `expiresAt` is an absolute epoch
@@ -145,6 +152,11 @@ interface CacheOptions {
     model?: string;
     /** Relative TTL in milliseconds; overrides the manager default. */
     ttl?: number;
+    /**
+     * Relative ms after which an entry is *stale* but still servable via
+     * `getOrRevalidate` (stale-while-revalidate). Should be less than `ttl`.
+     */
+    staleTtl?: number;
     /** When false, bypasses the cache entirely (read and write). */
     cache?: boolean;
     tokenCount?: number;
@@ -287,6 +299,10 @@ declare abstract class BaseCacheManager<T> {
     protected readonly metrics: MetricsSink;
     private hits;
     private misses;
+    /** Keys with an in-flight background revalidation, to avoid duplicate refreshes. */
+    private readonly refreshing;
+    /** In-flight generations, so concurrent misses for the same key run the generator once. */
+    private readonly inflight;
     constructor(options: BaseCacheManagerOptions<T>);
     /**
      * Builds the storage key for an input. Defaults to the canonical
@@ -303,6 +319,15 @@ declare abstract class BaseCacheManager<T> {
      * `options.cache = false` to bypass the cache for both read and write.
      */
     getOrGenerate(input: string, generator: () => Promise<T>, options?: CacheOptions): Promise<T>;
+    /**
+     * Stale-while-revalidate read-through. Like {@link getOrGenerate}, but when a
+     * cached entry is *stale* (past its `staleTtl`/`staleAt` but not yet expired)
+     * it is returned immediately and a fresh value is fetched in the background.
+     * Concurrent stale hits for the same key trigger at most one background
+     * refresh. A failed background refresh is swallowed and the stale value stands
+     * until it fully expires.
+     */
+    getOrRevalidate(input: string, generator: () => Promise<T>, options?: CacheOptions): Promise<T>;
     /**
      * Removes a single entry by its input (and namespacing options).
      */
@@ -311,6 +336,17 @@ declare abstract class BaseCacheManager<T> {
      * Returns hit/miss accounting for this manager plus the adapter's entry count.
      */
     stats(): Promise<CacheStats>;
+    /**
+     * Runs the generator and persists the result, deduplicating concurrent calls
+     * for the same key (singleflight): while one generation is in flight, other
+     * callers join it instead of invoking the generator again. Prevents a
+     * thundering herd of identical API calls on a cold key.
+     */
+    private coalescedGenerate;
+    /** Builds an entry, writes it through the adapter, and emits `cache.set`. */
+    private persist;
+    /** Fire-and-forget background refresh for a stale entry, coalesced per key. */
+    private revalidate;
 }
 
 export { type AdapterStats, BaseCacheManager, type BaseCacheManagerOptions, CacheAdapterError, type CacheEntry, type CacheMetadata, type CacheOptions, type CacheStats, type CacheType, type CompressedResult, type CompressionAlgo, type CompressionEngine, CompressionError, type CompressionStats, type DataHint, JsonSerializer, KeyBuilder, type LLMProvider, type MetricData, type MetricEvent, type MetricsSink, NodeLLMCacheError, SerializationError, type Serializer, type StorageAdapter, TTLManager, ValidationError, type VectorMatch, type VectorStoreAdapter, noopMetrics };

package/dist/index.d.ts

@@ -32,6 +32,13 @@ interface CacheMetadata {
     provider?: LLMProvider;
     model?: string;
     tokenCount?: number;
+    /**
+     * Absolute epoch ms after which the entry is considered *stale* but still
+     * usable. Used by stale-while-revalidate: a stale hit is served immediately
+     * while a fresh value is fetched in the background. Always earlier than
+     * `expiresAt`.
+     */
+    staleAt?: number;
 }
 /**
  * A single cached value with its bookkeeping. `expiresAt` is an absolute epoch
@@ -145,6 +152,11 @@ interface CacheOptions {
     model?: string;
     /** Relative TTL in milliseconds; overrides the manager default. */
     ttl?: number;
+    /**
+     * Relative ms after which an entry is *stale* but still servable via
+     * `getOrRevalidate` (stale-while-revalidate). Should be less than `ttl`.
+     */
+    staleTtl?: number;
     /** When false, bypasses the cache entirely (read and write). */
     cache?: boolean;
     tokenCount?: number;
@@ -287,6 +299,10 @@ declare abstract class BaseCacheManager<T> {
     protected readonly metrics: MetricsSink;
     private hits;
     private misses;
+    /** Keys with an in-flight background revalidation, to avoid duplicate refreshes. */
+    private readonly refreshing;
+    /** In-flight generations, so concurrent misses for the same key run the generator once. */
+    private readonly inflight;
     constructor(options: BaseCacheManagerOptions<T>);
     /**
      * Builds the storage key for an input. Defaults to the canonical
@@ -303,6 +319,15 @@ declare abstract class BaseCacheManager<T> {
      * `options.cache = false` to bypass the cache for both read and write.
      */
     getOrGenerate(input: string, generator: () => Promise<T>, options?: CacheOptions): Promise<T>;
+    /**
+     * Stale-while-revalidate read-through. Like {@link getOrGenerate}, but when a
+     * cached entry is *stale* (past its `staleTtl`/`staleAt` but not yet expired)
+     * it is returned immediately and a fresh value is fetched in the background.
+     * Concurrent stale hits for the same key trigger at most one background
+     * refresh. A failed background refresh is swallowed and the stale value stands
+     * until it fully expires.
+     */
+    getOrRevalidate(input: string, generator: () => Promise<T>, options?: CacheOptions): Promise<T>;
     /**
      * Removes a single entry by its input (and namespacing options).
      */
@@ -311,6 +336,17 @@ declare abstract class BaseCacheManager<T> {
      * Returns hit/miss accounting for this manager plus the adapter's entry count.
      */
     stats(): Promise<CacheStats>;
+    /**
+     * Runs the generator and persists the result, deduplicating concurrent calls
+     * for the same key (singleflight): while one generation is in flight, other
+     * callers join it instead of invoking the generator again. Prevents a
+     * thundering herd of identical API calls on a cold key.
+     */
+    private coalescedGenerate;
+    /** Builds an entry, writes it through the adapter, and emits `cache.set`. */
+    private persist;
+    /** Fire-and-forget background refresh for a stale entry, coalesced per key. */
+    private revalidate;
 }
 
 export { type AdapterStats, BaseCacheManager, type BaseCacheManagerOptions, CacheAdapterError, type CacheEntry, type CacheMetadata, type CacheOptions, type CacheStats, type CacheType, type CompressedResult, type CompressionAlgo, type CompressionEngine, CompressionError, type CompressionStats, type DataHint, JsonSerializer, KeyBuilder, type LLMProvider, type MetricData, type MetricEvent, type MetricsSink, NodeLLMCacheError, SerializationError, type Serializer, type StorageAdapter, TTLManager, ValidationError, type VectorMatch, type VectorStoreAdapter, noopMetrics };

package/dist/index.mjs

@@ -108,6 +108,10 @@ var BaseCacheManager = class {
   metrics;
   hits = 0;
   misses = 0;
+  /** Keys with an in-flight background revalidation, to avoid duplicate refreshes. */
+  refreshing = /* @__PURE__ */ new Set();
+  /** In-flight generations, so concurrent misses for the same key run the generator once. */
+  inflight = /* @__PURE__ */ new Map();
   constructor(options) {
     this.adapter = options.adapter;
     this.defaultTTL = options.defaultTTL;
@@ -131,6 +135,7 @@ var BaseCacheManager = class {
   buildEntry(key, value, options) {
     const createdAt = Date.now();
     const ttl = options?.ttl ?? this.defaultTTL;
+    const staleTtl = options?.staleTtl;
     return {
       key,
       value,
@@ -142,7 +147,8 @@ var BaseCacheManager = class {
         cacheType: this.cacheType,
         provider: options?.provider,
         model: options?.model,
-        tokenCount: options?.tokenCount
+        tokenCount: options?.tokenCount,
+        staleAt: staleTtl !== void 0 && staleTtl > 0 ? createdAt + staleTtl : void 0
       }
     };
   }
@@ -176,17 +182,46 @@ var BaseCacheManager = class {
       provider: options?.provider,
       model: options?.model
     });
-    const value = await generator();
-    const ttl = options?.ttl ?? this.defaultTTL;
-    const entry = this.buildEntry(key, value, options);
-    await this.adapter.set(key, entry, ttl);
-    this.metrics.emit("cache.set", {
+    return this.coalescedGenerate(key, generator, options, start);
+  }
+  /**
+   * Stale-while-revalidate read-through. Like {@link getOrGenerate}, but when a
+   * cached entry is *stale* (past its `staleTtl`/`staleAt` but not yet expired)
+   * it is returned immediately and a fresh value is fetched in the background.
+   * Concurrent stale hits for the same key trigger at most one background
+   * refresh. A failed background refresh is swallowed and the stale value stands
+   * until it fully expires.
+   */
+  async getOrRevalidate(input, generator, options) {
+    if (options?.cache === false) {
+      return generator();
+    }
+    const key = this.buildKey(input, options);
+    const start = Date.now();
+    const cached = await this.adapter.get(key);
+    if (cached && !TTLManager.isExpired(cached)) {
+      this.hits++;
+      this.metrics.emit("cache.hit", {
+        cacheType: this.cacheType,
+        latencyMs: Date.now() - start,
+        tokensSaved: cached.metadata.tokenCount,
+        provider: options?.provider,
+        model: options?.model
+      });
+      const staleAt = cached.metadata.staleAt;
+      if (staleAt !== void 0 && staleAt <= Date.now()) {
+        this.revalidate(key, generator, options);
+      }
+      return cached.value;
+    }
+    this.misses++;
+    this.metrics.emit("cache.miss", {
       cacheType: this.cacheType,
       latencyMs: Date.now() - start,
       provider: options?.provider,
       model: options?.model
     });
-    return value;
+    return this.coalescedGenerate(key, generator, options, start);
   }
   /**
    * Removes a single entry by its input (and namespacing options).
@@ -207,6 +242,49 @@ var BaseCacheManager = class {
       entryCount: adapterStats.entryCount
     };
   }
+  /**
+   * Runs the generator and persists the result, deduplicating concurrent calls
+   * for the same key (singleflight): while one generation is in flight, other
+   * callers join it instead of invoking the generator again. Prevents a
+   * thundering herd of identical API calls on a cold key.
+   */
+  coalescedGenerate(key, generator, options, start) {
+    const existing = this.inflight.get(key);
+    if (existing) return existing;
+    const promise = (async () => {
+      const value = await generator();
+      await this.persist(key, value, options, start);
+      return value;
+    })();
+    this.inflight.set(key, promise);
+    return promise.finally(() => this.inflight.delete(key));
+  }
+  /** Builds an entry, writes it through the adapter, and emits `cache.set`. */
+  async persist(key, value, options, start) {
+    const ttl = options?.ttl ?? this.defaultTTL;
+    const entry = this.buildEntry(key, value, options);
+    await this.adapter.set(key, entry, ttl);
+    this.metrics.emit("cache.set", {
+      cacheType: this.cacheType,
+      latencyMs: Date.now() - start,
+      provider: options?.provider,
+      model: options?.model
+    });
+  }
+  /** Fire-and-forget background refresh for a stale entry, coalesced per key. */
+  revalidate(key, generator, options) {
+    if (this.refreshing.has(key)) return;
+    this.refreshing.add(key);
+    void (async () => {
+      try {
+        const value = await generator();
+        await this.persist(key, value, options, Date.now());
+      } catch {
+      } finally {
+        this.refreshing.delete(key);
+      }
+    })();
+  }
 };
 export {
   BaseCacheManager,

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts","../src/KeyBuilder.ts","../src/TTLManager.ts","../src/Serializer.ts","../src/BaseCacheManager.ts"],"sourcesContent":["/**\n * Base class for every error thrown by NodeLLMCache packages. Catching this\n * catches anything the library throws intentionally.\n */\nexport class NodeLLMCacheError extends Error {\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options)\n    this.name = new.target.name\n    // Restore prototype chain for instanceof across the ES5 transpile boundary.\n    Object.setPrototypeOf(this, new.target.prototype)\n  }\n}\n\n/** Thrown when a storage adapter operation fails. */\nexport class CacheAdapterError extends NodeLLMCacheError {}\n\n/** Thrown when compression or decompression fails. */\nexport class CompressionError extends NodeLLMCacheError {}\n\n/** Thrown when serialization or deserialization fails. */\nexport class SerializationError extends NodeLLMCacheError {}\n\n/** Thrown when a value fails validation (e.g. malformed configuration). */\nexport class ValidationError extends NodeLLMCacheError {}\n","import { createHash } from 'node:crypto'\nimport type { CacheType, LLMProvider } from './types.js'\n\n/**\n * Builds deterministic, collision-resistant cache keys.\n *\n * Format: `{type}:{provider}:{model}:{sha256-hash}`\n *\n * The raw input text is normalized and hashed with SHA-256 — keys never\n * contain raw prompt text, which keeps sensitive content out of storage keys\n * and logs.\n */\nexport class KeyBuilder {\n  /**\n   * Normalizes text before hashing so trivially different inputs collapse to\n   * the same key: trims surrounding whitespace, lowercases, and collapses any\n   * run of whitespace to a single space.\n   */\n  static normalize(text: string): string {\n    return text.trim().toLowerCase().replace(/\\s+/g, ' ')\n  }\n\n  /**\n   * Produces the SHA-256 hex digest of the normalized text.\n   */\n  static hash(text: string): string {\n    return createHash('sha256').update(KeyBuilder.normalize(text)).digest('hex')\n  }\n\n  /**\n   * Builds a fully namespaced cache key.\n   *\n   * @example\n   * KeyBuilder.build('prompt', 'openai', 'gpt-4o', 'hello world')\n   * // 'prompt:openai:gpt-4o:b94d27b9...'\n   */\n  static build(\n    type: CacheType,\n    provider: LLMProvider | string,\n    model: string,\n    text: string,\n  ): string {\n    return `${type}:${provider}:${model}:${KeyBuilder.hash(text)}`\n  }\n}\n","import type { CacheEntry } from './interfaces.js'\n\n/**\n * Centralizes time-to-live arithmetic: computing expiry timestamps, checking\n * expiry, and supporting sliding-window refresh. All durations are relative\n * milliseconds; all timestamps are absolute epoch milliseconds.\n */\nexport class TTLManager {\n  /**\n   * Computes the absolute expiry timestamp for an entry created at `createdAt`\n   * with a relative `ttl`. Returns `undefined` when `ttl` is not a positive\n   * number, meaning the entry never expires.\n   */\n  static computeExpiresAt(createdAt: number, ttl?: number): number | undefined {\n    if (ttl === undefined || ttl <= 0) return undefined\n    return createdAt + ttl\n  }\n\n  /**\n   * Returns true when the entry has an expiry and that expiry is at or before\n   * `now` (defaults to the current time).\n   */\n  static isExpired(entry: Pick<CacheEntry<unknown>, 'expiresAt'>, now: number = Date.now()): boolean {\n    return entry.expiresAt !== undefined && entry.expiresAt <= now\n  }\n\n  /**\n   * Milliseconds remaining until the entry expires. Returns `Infinity` for\n   * entries with no expiry, and `0` for already-expired entries.\n   */\n  static remaining(entry: Pick<CacheEntry<unknown>, 'expiresAt'>, now: number = Date.now()): number {\n    if (entry.expiresAt === undefined) return Infinity\n    return Math.max(0, entry.expiresAt - now)\n  }\n\n  /**\n   * Computes a refreshed expiry for a sliding-window TTL: extends the entry's\n   * life by `ttl` from `now`. Returns `undefined` when `ttl` is not positive.\n   */\n  static slide(ttl?: number, now: number = Date.now()): number | undefined {\n    return TTLManager.computeExpiresAt(now, ttl)\n  }\n}\n","import { SerializationError } from './errors.js'\n\n/**\n * Converts values to and from `Buffer` for storage. Implementations decide the\n * wire format.\n *\n * The architecture calls for MessagePack as the primary format, but\n * `@nodellmcache/core` must stay dependency-free, so it ships only the JSON\n * implementation below. A MessagePack serializer can be supplied by an optional\n * package and injected wherever a `Serializer` is accepted.\n */\nexport interface Serializer {\n  serialize<T>(value: T): Buffer\n  deserialize<T>(data: Buffer): T\n}\n\n/**\n * Default JSON-backed serializer. Zero dependencies; handles the common case\n * and wraps failures in {@link SerializationError}.\n */\nexport class JsonSerializer implements Serializer {\n  serialize<T>(value: T): Buffer {\n    try {\n      return Buffer.from(JSON.stringify(value), 'utf8')\n    } catch (cause) {\n      throw new SerializationError('Failed to serialize value to JSON', { cause })\n    }\n  }\n\n  deserialize<T>(data: Buffer): T {\n    try {\n      return JSON.parse(data.toString('utf8')) as T\n    } catch (cause) {\n      throw new SerializationError('Failed to deserialize JSON value', { cause })\n    }\n  }\n}\n","import { KeyBuilder } from './KeyBuilder.js'\nimport { TTLManager } from './TTLManager.js'\nimport type {\n  CacheEntry,\n  CacheOptions,\n  CacheStats,\n  MetricsSink,\n  StorageAdapter,\n} from './interfaces.js'\nimport type { CacheType } from './types.js'\n\n/** A metrics sink that discards everything; the default when none is injected. */\nexport const noopMetrics: MetricsSink = {\n  emit() {\n    // intentionally empty\n  },\n}\n\n/**\n * Construction options shared by all cache managers.\n */\nexport interface BaseCacheManagerOptions<T> {\n  adapter: StorageAdapter<T>\n  /** Default relative TTL in milliseconds applied to entries lacking their own. */\n  defaultTTL?: number\n  /** Metrics sink; defaults to a no-op so core stays dependency-free. */\n  metrics?: MetricsSink\n}\n\n/**\n * Shared base for every feature cache (prompt, embedding, semantic, ...).\n *\n * Provides the cache-aside `getOrGenerate` flow, key building, entry\n * construction, invalidation, and hit/miss accounting. Subclasses declare their\n * {@link CacheType} and may override {@link buildKey} for custom namespacing.\n */\nexport abstract class BaseCacheManager<T> {\n  /** The workload category for keys and metrics. */\n  protected abstract readonly cacheType: CacheType\n\n  protected readonly adapter: StorageAdapter<T>\n  protected readonly defaultTTL: number | undefined\n  protected readonly metrics: MetricsSink\n\n  private hits = 0\n  private misses = 0\n\n  constructor(options: BaseCacheManagerOptions<T>) {\n    this.adapter = options.adapter\n    this.defaultTTL = options.defaultTTL\n    this.metrics = options.metrics ?? noopMetrics\n  }\n\n  /**\n   * Builds the storage key for an input. Defaults to the canonical\n   * `{type}:{provider}:{model}:{hash}` format via {@link KeyBuilder}.\n   */\n  protected buildKey(input: string, options?: CacheOptions): string {\n    return KeyBuilder.build(\n      this.cacheType,\n      options?.provider ?? 'unknown',\n      options?.model ?? 'default',\n      input,\n    )\n  }\n\n  /**\n   * Wraps a value in a {@link CacheEntry} with computed expiry and metadata.\n   */\n  protected buildEntry(key: string, value: T, options?: CacheOptions): CacheEntry<T> {\n    const createdAt = Date.now()\n    const ttl = options?.ttl ?? this.defaultTTL\n    return {\n      key,\n      value,\n      createdAt,\n      expiresAt: TTLManager.computeExpiresAt(createdAt, ttl),\n      metadata: {\n        compressed: false,\n        originalSize: 0,\n        cacheType: this.cacheType,\n        provider: options?.provider,\n        model: options?.model,\n        tokenCount: options?.tokenCount,\n      },\n    }\n  }\n\n  /**\n   * Cache-aside read-through. Returns the cached value on a hit, otherwise\n   * invokes `generator`, stores the result, and returns it. Set\n   * `options.cache = false` to bypass the cache for both read and write.\n   */\n  async getOrGenerate(\n    input: string,\n    generator: () => Promise<T>,\n    options?: CacheOptions,\n  ): Promise<T> {\n    // A deliberate bypass is neither a hit nor a miss — skip the cache and\n    // metrics entirely so accounting reflects only real cache consultations.\n    if (options?.cache === false) {\n      return generator()\n    }\n\n    const key = this.buildKey(input, options)\n    const start = Date.now()\n\n    const cached = await this.adapter.get(key)\n    if (cached && !TTLManager.isExpired(cached)) {\n      this.hits++\n      this.metrics.emit('cache.hit', {\n        cacheType: this.cacheType,\n        latencyMs: Date.now() - start,\n        tokensSaved: cached.metadata.tokenCount,\n        provider: options?.provider,\n        model: options?.model,\n      })\n      return cached.value\n    }\n\n    this.misses++\n    this.metrics.emit('cache.miss', {\n      cacheType: this.cacheType,\n      latencyMs: Date.now() - start,\n      provider: options?.provider,\n      model: options?.model,\n    })\n\n    const value = await generator()\n\n    const ttl = options?.ttl ?? this.defaultTTL\n    const entry = this.buildEntry(key, value, options)\n    await this.adapter.set(key, entry, ttl)\n    this.metrics.emit('cache.set', {\n      cacheType: this.cacheType,\n      latencyMs: Date.now() - start,\n      provider: options?.provider,\n      model: options?.model,\n    })\n\n    return value\n  }\n\n  /**\n   * Removes a single entry by its input (and namespacing options).\n   */\n  async invalidate(input: string, options?: CacheOptions): Promise<void> {\n    await this.adapter.delete(this.buildKey(input, options))\n  }\n\n  /**\n   * Returns hit/miss accounting for this manager plus the adapter's entry count.\n   */\n  async stats(): Promise<CacheStats> {\n    const total = this.hits + this.misses\n    const adapterStats = await this.adapter.stats()\n    return {\n      hits: this.hits,\n      misses: this.misses,\n      hitRate: total === 0 ? 0 : this.hits / total,\n      entryCount: adapterStats.entryCount,\n    }\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/errors.ts","../src/KeyBuilder.ts","../src/TTLManager.ts","../src/Serializer.ts","../src/BaseCacheManager.ts"],"sourcesContent":["/**\n * Base class for every error thrown by NodeLLMCache packages. Catching this\n * catches anything the library throws intentionally.\n */\nexport class NodeLLMCacheError extends Error {\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options)\n    this.name = new.target.name\n    // Restore prototype chain for instanceof across the ES5 transpile boundary.\n    Object.setPrototypeOf(this, new.target.prototype)\n  }\n}\n\n/** Thrown when a storage adapter operation fails. */\nexport class CacheAdapterError extends NodeLLMCacheError {}\n\n/** Thrown when compression or decompression fails. */\nexport class CompressionError extends NodeLLMCacheError {}\n\n/** Thrown when serialization or deserialization fails. */\nexport class SerializationError extends NodeLLMCacheError {}\n\n/** Thrown when a value fails validation (e.g. malformed configuration). */\nexport class ValidationError extends NodeLLMCacheError {}\n","import { createHash } from 'node:crypto'\nimport type { CacheType, LLMProvider } from './types.js'\n\n/**\n * Builds deterministic, collision-resistant cache keys.\n *\n * Format: `{type}:{provider}:{model}:{sha256-hash}`\n *\n * The raw input text is normalized and hashed with SHA-256 — keys never\n * contain raw prompt text, which keeps sensitive content out of storage keys\n * and logs.\n */\nexport class KeyBuilder {\n  /**\n   * Normalizes text before hashing so trivially different inputs collapse to\n   * the same key: trims surrounding whitespace, lowercases, and collapses any\n   * run of whitespace to a single space.\n   */\n  static normalize(text: string): string {\n    return text.trim().toLowerCase().replace(/\\s+/g, ' ')\n  }\n\n  /**\n   * Produces the SHA-256 hex digest of the normalized text.\n   */\n  static hash(text: string): string {\n    return createHash('sha256').update(KeyBuilder.normalize(text)).digest('hex')\n  }\n\n  /**\n   * Builds a fully namespaced cache key.\n   *\n   * @example\n   * KeyBuilder.build('prompt', 'openai', 'gpt-4o', 'hello world')\n   * // 'prompt:openai:gpt-4o:b94d27b9...'\n   */\n  static build(\n    type: CacheType,\n    provider: LLMProvider | string,\n    model: string,\n    text: string,\n  ): string {\n    return `${type}:${provider}:${model}:${KeyBuilder.hash(text)}`\n  }\n}\n","import type { CacheEntry } from './interfaces.js'\n\n/**\n * Centralizes time-to-live arithmetic: computing expiry timestamps, checking\n * expiry, and supporting sliding-window refresh. All durations are relative\n * milliseconds; all timestamps are absolute epoch milliseconds.\n */\nexport class TTLManager {\n  /**\n   * Computes the absolute expiry timestamp for an entry created at `createdAt`\n   * with a relative `ttl`. Returns `undefined` when `ttl` is not a positive\n   * number, meaning the entry never expires.\n   */\n  static computeExpiresAt(createdAt: number, ttl?: number): number | undefined {\n    if (ttl === undefined || ttl <= 0) return undefined\n    return createdAt + ttl\n  }\n\n  /**\n   * Returns true when the entry has an expiry and that expiry is at or before\n   * `now` (defaults to the current time).\n   */\n  static isExpired(entry: Pick<CacheEntry<unknown>, 'expiresAt'>, now: number = Date.now()): boolean {\n    return entry.expiresAt !== undefined && entry.expiresAt <= now\n  }\n\n  /**\n   * Milliseconds remaining until the entry expires. Returns `Infinity` for\n   * entries with no expiry, and `0` for already-expired entries.\n   */\n  static remaining(entry: Pick<CacheEntry<unknown>, 'expiresAt'>, now: number = Date.now()): number {\n    if (entry.expiresAt === undefined) return Infinity\n    return Math.max(0, entry.expiresAt - now)\n  }\n\n  /**\n   * Computes a refreshed expiry for a sliding-window TTL: extends the entry's\n   * life by `ttl` from `now`. Returns `undefined` when `ttl` is not positive.\n   */\n  static slide(ttl?: number, now: number = Date.now()): number | undefined {\n    return TTLManager.computeExpiresAt(now, ttl)\n  }\n}\n","import { SerializationError } from './errors.js'\n\n/**\n * Converts values to and from `Buffer` for storage. Implementations decide the\n * wire format.\n *\n * The architecture calls for MessagePack as the primary format, but\n * `@nodellmcache/core` must stay dependency-free, so it ships only the JSON\n * implementation below. A MessagePack serializer can be supplied by an optional\n * package and injected wherever a `Serializer` is accepted.\n */\nexport interface Serializer {\n  serialize<T>(value: T): Buffer\n  deserialize<T>(data: Buffer): T\n}\n\n/**\n * Default JSON-backed serializer. Zero dependencies; handles the common case\n * and wraps failures in {@link SerializationError}.\n */\nexport class JsonSerializer implements Serializer {\n  serialize<T>(value: T): Buffer {\n    try {\n      return Buffer.from(JSON.stringify(value), 'utf8')\n    } catch (cause) {\n      throw new SerializationError('Failed to serialize value to JSON', { cause })\n    }\n  }\n\n  deserialize<T>(data: Buffer): T {\n    try {\n      return JSON.parse(data.toString('utf8')) as T\n    } catch (cause) {\n      throw new SerializationError('Failed to deserialize JSON value', { cause })\n    }\n  }\n}\n","import { KeyBuilder } from './KeyBuilder.js'\nimport { TTLManager } from './TTLManager.js'\nimport type {\n  CacheEntry,\n  CacheOptions,\n  CacheStats,\n  MetricsSink,\n  StorageAdapter,\n} from './interfaces.js'\nimport type { CacheType } from './types.js'\n\n/** A metrics sink that discards everything; the default when none is injected. */\nexport const noopMetrics: MetricsSink = {\n  emit() {\n    // intentionally empty\n  },\n}\n\n/**\n * Construction options shared by all cache managers.\n */\nexport interface BaseCacheManagerOptions<T> {\n  adapter: StorageAdapter<T>\n  /** Default relative TTL in milliseconds applied to entries lacking their own. */\n  defaultTTL?: number\n  /** Metrics sink; defaults to a no-op so core stays dependency-free. */\n  metrics?: MetricsSink\n}\n\n/**\n * Shared base for every feature cache (prompt, embedding, semantic, ...).\n *\n * Provides the cache-aside `getOrGenerate` flow, key building, entry\n * construction, invalidation, and hit/miss accounting. Subclasses declare their\n * {@link CacheType} and may override {@link buildKey} for custom namespacing.\n */\nexport abstract class BaseCacheManager<T> {\n  /** The workload category for keys and metrics. */\n  protected abstract readonly cacheType: CacheType\n\n  protected readonly adapter: StorageAdapter<T>\n  protected readonly defaultTTL: number | undefined\n  protected readonly metrics: MetricsSink\n\n  private hits = 0\n  private misses = 0\n  /** Keys with an in-flight background revalidation, to avoid duplicate refreshes. */\n  private readonly refreshing = new Set<string>()\n  /** In-flight generations, so concurrent misses for the same key run the generator once. */\n  private readonly inflight = new Map<string, Promise<T>>()\n\n  constructor(options: BaseCacheManagerOptions<T>) {\n    this.adapter = options.adapter\n    this.defaultTTL = options.defaultTTL\n    this.metrics = options.metrics ?? noopMetrics\n  }\n\n  /**\n   * Builds the storage key for an input. Defaults to the canonical\n   * `{type}:{provider}:{model}:{hash}` format via {@link KeyBuilder}.\n   */\n  protected buildKey(input: string, options?: CacheOptions): string {\n    return KeyBuilder.build(\n      this.cacheType,\n      options?.provider ?? 'unknown',\n      options?.model ?? 'default',\n      input,\n    )\n  }\n\n  /**\n   * Wraps a value in a {@link CacheEntry} with computed expiry and metadata.\n   */\n  protected buildEntry(key: string, value: T, options?: CacheOptions): CacheEntry<T> {\n    const createdAt = Date.now()\n    const ttl = options?.ttl ?? this.defaultTTL\n    const staleTtl = options?.staleTtl\n    return {\n      key,\n      value,\n      createdAt,\n      expiresAt: TTLManager.computeExpiresAt(createdAt, ttl),\n      metadata: {\n        compressed: false,\n        originalSize: 0,\n        cacheType: this.cacheType,\n        provider: options?.provider,\n        model: options?.model,\n        tokenCount: options?.tokenCount,\n        staleAt:\n          staleTtl !== undefined && staleTtl > 0 ? createdAt + staleTtl : undefined,\n      },\n    }\n  }\n\n  /**\n   * Cache-aside read-through. Returns the cached value on a hit, otherwise\n   * invokes `generator`, stores the result, and returns it. Set\n   * `options.cache = false` to bypass the cache for both read and write.\n   */\n  async getOrGenerate(\n    input: string,\n    generator: () => Promise<T>,\n    options?: CacheOptions,\n  ): Promise<T> {\n    // A deliberate bypass is neither a hit nor a miss — skip the cache and\n    // metrics entirely so accounting reflects only real cache consultations.\n    if (options?.cache === false) {\n      return generator()\n    }\n\n    const key = this.buildKey(input, options)\n    const start = Date.now()\n\n    const cached = await this.adapter.get(key)\n    if (cached && !TTLManager.isExpired(cached)) {\n      this.hits++\n      this.metrics.emit('cache.hit', {\n        cacheType: this.cacheType,\n        latencyMs: Date.now() - start,\n        tokensSaved: cached.metadata.tokenCount,\n        provider: options?.provider,\n        model: options?.model,\n      })\n      return cached.value\n    }\n\n    this.misses++\n    this.metrics.emit('cache.miss', {\n      cacheType: this.cacheType,\n      latencyMs: Date.now() - start,\n      provider: options?.provider,\n      model: options?.model,\n    })\n\n    return this.coalescedGenerate(key, generator, options, start)\n  }\n\n  /**\n   * Stale-while-revalidate read-through. Like {@link getOrGenerate}, but when a\n   * cached entry is *stale* (past its `staleTtl`/`staleAt` but not yet expired)\n   * it is returned immediately and a fresh value is fetched in the background.\n   * Concurrent stale hits for the same key trigger at most one background\n   * refresh. A failed background refresh is swallowed and the stale value stands\n   * until it fully expires.\n   */\n  async getOrRevalidate(\n    input: string,\n    generator: () => Promise<T>,\n    options?: CacheOptions,\n  ): Promise<T> {\n    if (options?.cache === false) {\n      return generator()\n    }\n\n    const key = this.buildKey(input, options)\n    const start = Date.now()\n\n    const cached = await this.adapter.get(key)\n    if (cached && !TTLManager.isExpired(cached)) {\n      this.hits++\n      this.metrics.emit('cache.hit', {\n        cacheType: this.cacheType,\n        latencyMs: Date.now() - start,\n        tokensSaved: cached.metadata.tokenCount,\n        provider: options?.provider,\n        model: options?.model,\n      })\n      const staleAt = cached.metadata.staleAt\n      if (staleAt !== undefined && staleAt <= Date.now()) {\n        this.revalidate(key, generator, options)\n      }\n      return cached.value\n    }\n\n    this.misses++\n    this.metrics.emit('cache.miss', {\n      cacheType: this.cacheType,\n      latencyMs: Date.now() - start,\n      provider: options?.provider,\n      model: options?.model,\n    })\n\n    return this.coalescedGenerate(key, generator, options, start)\n  }\n\n  /**\n   * Removes a single entry by its input (and namespacing options).\n   */\n  async invalidate(input: string, options?: CacheOptions): Promise<void> {\n    await this.adapter.delete(this.buildKey(input, options))\n  }\n\n  /**\n   * Returns hit/miss accounting for this manager plus the adapter's entry count.\n   */\n  async stats(): Promise<CacheStats> {\n    const total = this.hits + this.misses\n    const adapterStats = await this.adapter.stats()\n    return {\n      hits: this.hits,\n      misses: this.misses,\n      hitRate: total === 0 ? 0 : this.hits / total,\n      entryCount: adapterStats.entryCount,\n    }\n  }\n\n  /**\n   * Runs the generator and persists the result, deduplicating concurrent calls\n   * for the same key (singleflight): while one generation is in flight, other\n   * callers join it instead of invoking the generator again. Prevents a\n   * thundering herd of identical API calls on a cold key.\n   */\n  private coalescedGenerate(\n    key: string,\n    generator: () => Promise<T>,\n    options: CacheOptions | undefined,\n    start: number,\n  ): Promise<T> {\n    const existing = this.inflight.get(key)\n    if (existing) return existing\n\n    const promise = (async () => {\n      const value = await generator()\n      await this.persist(key, value, options, start)\n      return value\n    })()\n    this.inflight.set(key, promise)\n    return promise.finally(() => this.inflight.delete(key))\n  }\n\n  /** Builds an entry, writes it through the adapter, and emits `cache.set`. */\n  private async persist(\n    key: string,\n    value: T,\n    options: CacheOptions | undefined,\n    start: number,\n  ): Promise<void> {\n    const ttl = options?.ttl ?? this.defaultTTL\n    const entry = this.buildEntry(key, value, options)\n    await this.adapter.set(key, entry, ttl)\n    this.metrics.emit('cache.set', {\n      cacheType: this.cacheType,\n      latencyMs: Date.now() - start,\n      provider: options?.provider,\n      model: options?.model,\n    })\n  }\n\n  /** Fire-and-forget background refresh for a stale entry, coalesced per key. */\n  private revalidate(key: string, generator: () => Promise<T>, options?: CacheOptions): void {\n    if (this.refreshing.has(key)) return\n    this.refreshing.add(key)\n    void (async () => {\n      try {\n        const value = await generator()\n        await this.persist(key, value, options, Date.now())\n      } catch {\n        // Swallow background-refresh failures: the stale value stands until expiry.\n      } finally {\n        this.refreshing.delete(key)\n      }\n    })()\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "@nodellmcache/core",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "Shared interfaces, types, and utilities for NodeLLMCache — AI memory infrastructure for Node.js",
-  "keywords": ["llm", "cache", "ai", "memory", "nodejs", "embeddings"],
+  "keywords": [
+    "llm",
+    "cache",
+    "ai",
+    "memory",
+    "nodejs",
+    "embeddings"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -22,15 +29,11 @@
       "require": "./dist/index.cjs"
     }
   },
-  "files": ["dist", "README.md", "CHANGELOG.md"],
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "echo \"no lint configured\""
-  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "devDependencies": {
     "@types/node": "^20.0.0",
     "tsup": "^8.0.0",
@@ -40,5 +43,13 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"no lint configured\""
   }
-}
+}