@nodellmcache/core 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# @nodellmcache/core
+
+Shared interfaces, types, and utilities for [NodeLLMCache](https://github.com/mdmax007/node-llm-cache) — AI memory infrastructure for Node.js.
+
+This is the central package every other `@nodellmcache/*` package depends on. It has **zero external dependencies** and exports only contracts and small, pure utilities. You rarely install it directly; a feature package (e.g. `@nodellmcache/prompt-cache`) pulls it in.
+
+## Install
+
+```bash
+npm install @nodellmcache/core
+```
+
+## What's inside
+
+- **Interfaces** — `StorageAdapter`, `VectorStoreAdapter`, `CompressionEngine`, `CacheEntry`, `CacheMetadata`, `MetricsSink`, `CacheOptions`
+- **Types** — `CacheType`, `LLMProvider`, `CompressionAlgo`, `DataHint`
+- **`KeyBuilder`** — deterministic, hashed cache keys
+- **`TTLManager`** — expiry arithmetic and sliding windows
+- **`Serializer` / `JsonSerializer`** — pluggable value encoding
+- **`BaseCacheManager`** — the cache-aside base class for every feature cache
+- **Error hierarchy** — `NodeLLMCacheError` and typed subclasses
+
+## Quick start
+
+### Building keys
+
+Keys follow the format `{type}:{provider}:{model}:{sha256}`. The raw input is normalized (`trim` → `toLowerCase` → collapse whitespace) and hashed, so **raw prompt text never appears in a key**.
+
+```ts
+import { KeyBuilder } from '@nodellmcache/core'
+
+KeyBuilder.build('prompt', 'openai', 'gpt-4o', 'Hello   World')
+// 'prompt:openai:gpt-4o:<sha256-of "hello world">'
+```
+
+### Implementing a storage adapter
+
+```ts
+import type { StorageAdapter, CacheEntry, AdapterStats } from '@nodellmcache/core'
+
+class MyAdapter<T> implements StorageAdapter<T> {
+  async get(key: string): Promise<CacheEntry<T> | null> { /* ... */ }
+  async set(key: string, entry: CacheEntry<T>, ttl?: number): Promise<void> { /* ... */ }
+  async delete(key: string): Promise<void> { /* ... */ }
+  async clear(): Promise<void> { /* ... */ }
+  async has(key: string): Promise<boolean> { /* ... */ }
+  async stats(): Promise<AdapterStats> { /* ... */ }
+}
+```
+
+### Building a feature cache
+
+`BaseCacheManager` provides the cache-aside `getOrGenerate` flow, key building, TTL handling, hit/miss accounting, and metric emission. Subclasses only declare their `cacheType`.
+
+```ts
+import { BaseCacheManager } from '@nodellmcache/core'
+
+class PromptCache extends BaseCacheManager<string> {
+  protected readonly cacheType = 'prompt' as const
+}
+
+const cache = new PromptCache({ adapter: myAdapter, defaultTTL: 3_600_000 })
+
+const answer = await cache.getOrGenerate(
+  'Explain Redis in one paragraph',
+  () => callTheModel(),
+  { provider: 'openai', model: 'gpt-4o' },
+)
+```
+
+## API summary
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `KeyBuilder.build/normalize/hash` | class (static) | Cache key generation |
+| `TTLManager.computeExpiresAt/isExpired/remaining/slide` | class (static) | TTL arithmetic |
+| `JsonSerializer` | class | Default JSON value codec (implements `Serializer`) |
+| `BaseCacheManager` | abstract class | Cache-aside base for feature caches |
+| `StorageAdapter<T>` | interface | Backend contract |
+| `VectorStoreAdapter<M>` | interface | Vector DB contract |
+| `CompressionEngine` | interface | Compression contract |
+| `MetricsSink` | interface | Metrics emission contract |
+| `NodeLLMCacheError` + subclasses | classes | Typed error hierarchy |
+
+## Notes
+
+- The architecture specifies MessagePack as the primary serialization format. To keep `core` dependency-free, this package ships only `JsonSerializer`; a MessagePack `Serializer` can be supplied by an optional package and injected wherever a `Serializer` is accepted.
+- `MetricsSink` defaults to a no-op (`noopMetrics`). Wire in `@nodellmcache/observability` to collect real metrics.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,259 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BaseCacheManager: () => BaseCacheManager,
+  CacheAdapterError: () => CacheAdapterError,
+  CompressionError: () => CompressionError,
+  JsonSerializer: () => JsonSerializer,
+  KeyBuilder: () => KeyBuilder,
+  NodeLLMCacheError: () => NodeLLMCacheError,
+  SerializationError: () => SerializationError,
+  TTLManager: () => TTLManager,
+  ValidationError: () => ValidationError,
+  noopMetrics: () => noopMetrics
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var NodeLLMCacheError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = new.target.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var CacheAdapterError = class extends NodeLLMCacheError {
+};
+var CompressionError = class extends NodeLLMCacheError {
+};
+var SerializationError = class extends NodeLLMCacheError {
+};
+var ValidationError = class extends NodeLLMCacheError {
+};
+
+// src/KeyBuilder.ts
+var import_node_crypto = require("crypto");
+var KeyBuilder = class _KeyBuilder {
+  /**
+   * Normalizes text before hashing so trivially different inputs collapse to
+   * the same key: trims surrounding whitespace, lowercases, and collapses any
+   * run of whitespace to a single space.
+   */
+  static normalize(text) {
+    return text.trim().toLowerCase().replace(/\s+/g, " ");
+  }
+  /**
+   * Produces the SHA-256 hex digest of the normalized text.
+   */
+  static hash(text) {
+    return (0, import_node_crypto.createHash)("sha256").update(_KeyBuilder.normalize(text)).digest("hex");
+  }
+  /**
+   * Builds a fully namespaced cache key.
+   *
+   * @example
+   * KeyBuilder.build('prompt', 'openai', 'gpt-4o', 'hello world')
+   * // 'prompt:openai:gpt-4o:b94d27b9...'
+   */
+  static build(type, provider, model, text) {
+    return `${type}:${provider}:${model}:${_KeyBuilder.hash(text)}`;
+  }
+};
+
+// src/TTLManager.ts
+var TTLManager = class _TTLManager {
+  /**
+   * Computes the absolute expiry timestamp for an entry created at `createdAt`
+   * with a relative `ttl`. Returns `undefined` when `ttl` is not a positive
+   * number, meaning the entry never expires.
+   */
+  static computeExpiresAt(createdAt, ttl) {
+    if (ttl === void 0 || ttl <= 0) return void 0;
+    return createdAt + ttl;
+  }
+  /**
+   * Returns true when the entry has an expiry and that expiry is at or before
+   * `now` (defaults to the current time).
+   */
+  static isExpired(entry, now = Date.now()) {
+    return entry.expiresAt !== void 0 && entry.expiresAt <= now;
+  }
+  /**
+   * Milliseconds remaining until the entry expires. Returns `Infinity` for
+   * entries with no expiry, and `0` for already-expired entries.
+   */
+  static remaining(entry, now = Date.now()) {
+    if (entry.expiresAt === void 0) return Infinity;
+    return Math.max(0, entry.expiresAt - now);
+  }
+  /**
+   * Computes a refreshed expiry for a sliding-window TTL: extends the entry's
+   * life by `ttl` from `now`. Returns `undefined` when `ttl` is not positive.
+   */
+  static slide(ttl, now = Date.now()) {
+    return _TTLManager.computeExpiresAt(now, ttl);
+  }
+};
+
+// src/Serializer.ts
+var JsonSerializer = class {
+  serialize(value) {
+    try {
+      return Buffer.from(JSON.stringify(value), "utf8");
+    } catch (cause) {
+      throw new SerializationError("Failed to serialize value to JSON", { cause });
+    }
+  }
+  deserialize(data) {
+    try {
+      return JSON.parse(data.toString("utf8"));
+    } catch (cause) {
+      throw new SerializationError("Failed to deserialize JSON value", { cause });
+    }
+  }
+};
+
+// src/BaseCacheManager.ts
+var noopMetrics = {
+  emit() {
+  }
+};
+var BaseCacheManager = class {
+  adapter;
+  defaultTTL;
+  metrics;
+  hits = 0;
+  misses = 0;
+  constructor(options) {
+    this.adapter = options.adapter;
+    this.defaultTTL = options.defaultTTL;
+    this.metrics = options.metrics ?? noopMetrics;
+  }
+  /**
+   * Builds the storage key for an input. Defaults to the canonical
+   * `{type}:{provider}:{model}:{hash}` format via {@link KeyBuilder}.
+   */
+  buildKey(input, options) {
+    return KeyBuilder.build(
+      this.cacheType,
+      options?.provider ?? "unknown",
+      options?.model ?? "default",
+      input
+    );
+  }
+  /**
+   * Wraps a value in a {@link CacheEntry} with computed expiry and metadata.
+   */
+  buildEntry(key, value, options) {
+    const createdAt = Date.now();
+    const ttl = options?.ttl ?? this.defaultTTL;
+    return {
+      key,
+      value,
+      createdAt,
+      expiresAt: TTLManager.computeExpiresAt(createdAt, ttl),
+      metadata: {
+        compressed: false,
+        originalSize: 0,
+        cacheType: this.cacheType,
+        provider: options?.provider,
+        model: options?.model,
+        tokenCount: options?.tokenCount
+      }
+    };
+  }
+  /**
+   * Cache-aside read-through. Returns the cached value on a hit, otherwise
+   * invokes `generator`, stores the result, and returns it. Set
+   * `options.cache = false` to bypass the cache for both read and write.
+   */
+  async getOrGenerate(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
+      });
+      return cached.value;
+    }
+    this.misses++;
+    this.metrics.emit("cache.miss", {
+      cacheType: this.cacheType,
+      latencyMs: Date.now() - start,
+      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", {
+      cacheType: this.cacheType,
+      latencyMs: Date.now() - start,
+      provider: options?.provider,
+      model: options?.model
+    });
+    return value;
+  }
+  /**
+   * Removes a single entry by its input (and namespacing options).
+   */
+  async invalidate(input, options) {
+    await this.adapter.delete(this.buildKey(input, options));
+  }
+  /**
+   * Returns hit/miss accounting for this manager plus the adapter's entry count.
+   */
+  async stats() {
+    const total = this.hits + this.misses;
+    const adapterStats = await this.adapter.stats();
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total === 0 ? 0 : this.hits / total,
+      entryCount: adapterStats.entryCount
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BaseCacheManager,
+  CacheAdapterError,
+  CompressionError,
+  JsonSerializer,
+  KeyBuilder,
+  NodeLLMCacheError,
+  SerializationError,
+  TTLManager,
+  ValidationError,
+  noopMetrics
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACIO,IAAM,oBAAN,cAAgC,MAAM;AAAA,EAC3C,YAAY,SAAiB,SAAwB;AACnD,UAAM,SAAS,OAAO;AACtB,SAAK,OAAO,WAAW;AAEvB,WAAO,eAAe,MAAM,WAAW,SAAS;AAAA,EAClD;AACF;AAGO,IAAM,oBAAN,cAAgC,kBAAkB;AAAC;AAGnD,IAAM,mBAAN,cAA+B,kBAAkB;AAAC;AAGlD,IAAM,qBAAN,cAAiC,kBAAkB;AAAC;AAGpD,IAAM,kBAAN,cAA8B,kBAAkB;AAAC;;;ACvBxD,yBAA2B;AAYpB,IAAM,aAAN,MAAM,YAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMtB,OAAO,UAAU,MAAsB;AACrC,WAAO,KAAK,KAAK,EAAE,YAAY,EAAE,QAAQ,QAAQ,GAAG;AAAA,EACtD;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,KAAK,MAAsB;AAChC,eAAO,+BAAW,QAAQ,EAAE,OAAO,YAAW,UAAU,IAAI,CAAC,EAAE,OAAO,KAAK;AAAA,EAC7E;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,OAAO,MACL,MACA,UACA,OACA,MACQ;AACR,WAAO,GAAG,IAAI,IAAI,QAAQ,IAAI,KAAK,IAAI,YAAW,KAAK,IAAI,CAAC;AAAA,EAC9D;AACF;;;ACrCO,IAAM,aAAN,MAAM,YAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMtB,OAAO,iBAAiB,WAAmB,KAAkC;AAC3E,QAAI,QAAQ,UAAa,OAAO,EAAG,QAAO;AAC1C,WAAO,YAAY;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAO,UAAU,OAA+C,MAAc,KAAK,IAAI,GAAY;AACjG,WAAO,MAAM,cAAc,UAAa,MAAM,aAAa;AAAA,EAC7D;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAO,UAAU,OAA+C,MAAc,KAAK,IAAI,GAAW;AAChG,QAAI,MAAM,cAAc,OAAW,QAAO;AAC1C,WAAO,KAAK,IAAI,GAAG,MAAM,YAAY,GAAG;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAO,MAAM,KAAc,MAAc,KAAK,IAAI,GAAuB;AACvE,WAAO,YAAW,iBAAiB,KAAK,GAAG;AAAA,EAC7C;AACF;;;ACtBO,IAAM,iBAAN,MAA2C;AAAA,EAChD,UAAa,OAAkB;AAC7B,QAAI;AACF,aAAO,OAAO,KAAK,KAAK,UAAU,KAAK,GAAG,MAAM;AAAA,IAClD,SAAS,OAAO;AACd,YAAM,IAAI,mBAAmB,qCAAqC,EAAE,MAAM,CAAC;AAAA,IAC7E;AAAA,EACF;AAAA,EAEA,YAAe,MAAiB;AAC9B,QAAI;AACF,aAAO,KAAK,MAAM,KAAK,SAAS,MAAM,CAAC;AAAA,IACzC,SAAS,OAAO;AACd,YAAM,IAAI,mBAAmB,oCAAoC,EAAE,MAAM,CAAC;AAAA,IAC5E;AAAA,EACF;AACF;;;ACxBO,IAAM,cAA2B;AAAA,EACtC,OAAO;AAAA,EAEP;AACF;AAoBO,IAAe,mBAAf,MAAmC;AAAA,EAIrB;AAAA,EACA;AAAA,EACA;AAAA,EAEX,OAAO;AAAA,EACP,SAAS;AAAA,EAEjB,YAAY,SAAqC;AAC/C,SAAK,UAAU,QAAQ;AACvB,SAAK,aAAa,QAAQ;AAC1B,SAAK,UAAU,QAAQ,WAAW;AAAA,EACpC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMU,SAAS,OAAe,SAAgC;AAChE,WAAO,WAAW;AAAA,MAChB,KAAK;AAAA,MACL,SAAS,YAAY;AAAA,MACrB,SAAS,SAAS;AAAA,MAClB;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKU,WAAW,KAAa,OAAU,SAAuC;AACjF,UAAM,YAAY,KAAK,IAAI;AAC3B,UAAM,MAAM,SAAS,OAAO,KAAK;AACjC,WAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,MACA,WAAW,WAAW,iBAAiB,WAAW,GAAG;AAAA,MACrD,UAAU;AAAA,QACR,YAAY;AAAA,QACZ,cAAc;AAAA,QACd,WAAW,KAAK;AAAA,QAChB,UAAU,SAAS;AAAA,QACnB,OAAO,SAAS;AAAA,QAChB,YAAY,SAAS;AAAA,MACvB;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,cACJ,OACA,WACA,SACY;AAGZ,QAAI,SAAS,UAAU,OAAO;AAC5B,aAAO,UAAU;AAAA,IACnB;AAEA,UAAM,MAAM,KAAK,SAAS,OAAO,OAAO;AACxC,UAAM,QAAQ,KAAK,IAAI;AAEvB,UAAM,SAAS,MAAM,KAAK,QAAQ,IAAI,GAAG;AACzC,QAAI,UAAU,CAAC,WAAW,UAAU,MAAM,GAAG;AAC3C,WAAK;AACL,WAAK,QAAQ,KAAK,aAAa;AAAA,QAC7B,WAAW,KAAK;AAAA,QAChB,WAAW,KAAK,IAAI,IAAI;AAAA,QACxB,aAAa,OAAO,SAAS;AAAA,QAC7B,UAAU,SAAS;AAAA,QACnB,OAAO,SAAS;AAAA,MAClB,CAAC;AACD,aAAO,OAAO;AAAA,IAChB;AAEA,SAAK;AACL,SAAK,QAAQ,KAAK,cAAc;AAAA,MAC9B,WAAW,KAAK;AAAA,MAChB,WAAW,KAAK,IAAI,IAAI;AAAA,MACxB,UAAU,SAAS;AAAA,MACnB,OAAO,SAAS;AAAA,IAClB,CAAC;AAED,UAAM,QAAQ,MAAM,UAAU;AAE9B,UAAM,MAAM,SAAS,OAAO,KAAK;AACjC,UAAM,QAAQ,KAAK,WAAW,KAAK,OAAO,OAAO;AACjD,UAAM,KAAK,QAAQ,IAAI,KAAK,OAAO,GAAG;AACtC,SAAK,QAAQ,KAAK,aAAa;AAAA,MAC7B,WAAW,KAAK;AAAA,MAChB,WAAW,KAAK,IAAI,IAAI;AAAA,MACxB,UAAU,SAAS;AAAA,MACnB,OAAO,SAAS;AAAA,IAClB,CAAC;AAED,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,WAAW,OAAe,SAAuC;AACrE,UAAM,KAAK,QAAQ,OAAO,KAAK,SAAS,OAAO,OAAO,CAAC;AAAA,EACzD;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,QAA6B;AACjC,UAAM,QAAQ,KAAK,OAAO,KAAK;AAC/B,UAAM,eAAe,MAAM,KAAK,QAAQ,MAAM;AAC9C,WAAO;AAAA,MACL,MAAM,KAAK;AAAA,MACX,QAAQ,KAAK;AAAA,MACb,SAAS,UAAU,IAAI,IAAI,KAAK,OAAO;AAAA,MACvC,YAAY,aAAa;AAAA,IAC3B;AAAA,EACF;AACF;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,316 @@
+/**
+ * The category of data a cache stores. Used in key namespacing and metrics
+ * breakdowns so every cached value is attributable to a workload.
+ */
+type CacheType = 'prompt' | 'embedding' | 'semantic' | 'retrieval' | 'context' | 'agent' | 'tool' | 'conversation';
+/**
+ * Canonical LLM provider names. See the providers table in CLAUDE.md for the
+ * common models associated with each.
+ */
+type LLMProvider = 'openai' | 'anthropic' | 'gemini' | 'deepseek' | 'llama' | 'mistral' | 'ollama';
+/**
+ * Supported compression algorithms. `auto` defers the choice to the
+ * compression engine's size/hint heuristics; `none` is a passthrough.
+ */
+type CompressionAlgo = 'lz4' | 'brotli' | 'zstd' | 'gzip' | 'none' | 'auto';
+/**
+ * A hint describing the shape of a payload so the compression engine can pick
+ * the best codec (e.g. `embedding` favours lz4, `text` favours brotli).
+ */
+type DataHint = 'embedding' | 'text' | 'json' | 'binary';
+
+/**
+ * Metadata stored alongside every cache entry. Captures how the value was
+ * encoded and which LLM workload produced it.
+ */
+interface CacheMetadata {
+    compressed: boolean;
+    compressionAlgo?: CompressionAlgo;
+    originalSize: number;
+    compressedSize?: number;
+    cacheType: CacheType;
+    provider?: LLMProvider;
+    model?: string;
+    tokenCount?: number;
+}
+/**
+ * A single cached value with its bookkeeping. `expiresAt` is an absolute epoch
+ * timestamp in milliseconds; when omitted the entry never expires.
+ */
+interface CacheEntry<T> {
+    key: string;
+    value: T;
+    createdAt: number;
+    expiresAt?: number;
+    metadata: CacheMetadata;
+}
+/**
+ * Aggregate statistics reported by a storage adapter.
+ */
+interface AdapterStats {
+    /** Number of entries currently held. */
+    entryCount: number;
+    /** Approximate bytes used by stored entries, if the adapter can measure it. */
+    sizeBytes?: number;
+    /** Number of evictions performed over the adapter's lifetime. */
+    evictions?: number;
+}
+/**
+ * The contract every storage backend implements. Application code never
+ * imports a concrete adapter in business logic — adapters are injected.
+ */
+interface StorageAdapter<T = unknown> {
+    get(key: string): Promise<CacheEntry<T> | null>;
+    /** `ttl` is a relative duration in milliseconds from now. */
+    set(key: string, entry: CacheEntry<T>, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    stats(): Promise<AdapterStats>;
+}
+/**
+ * Result of a single compression operation.
+ */
+interface CompressedResult {
+    data: Buffer;
+    algo: CompressionAlgo;
+    originalSize: number;
+    compressedSize: number;
+    ratio: number;
+    durationMs: number;
+}
+/**
+ * Statistics for a completed compression, suitable for observability rollups.
+ */
+interface CompressionStats {
+    originalSize: number;
+    compressedSize: number;
+    ratio: number;
+    savedBytes: number;
+    savedPercent: number;
+}
+/**
+ * The compression engine contract implemented by `@nodellmcache/compression`.
+ */
+interface CompressionEngine {
+    compress(data: Buffer, algo: CompressionAlgo): Promise<Buffer>;
+    decompress(data: Buffer, algo: CompressionAlgo): Promise<Buffer>;
+    auto(data: Buffer, hint?: DataHint): Promise<CompressedResult>;
+    stats(original: Buffer, compressed: Buffer): CompressionStats;
+}
+/**
+ * A vector match returned by a vector store query.
+ */
+interface VectorMatch<M = Record<string, unknown>> {
+    id: string;
+    score: number;
+    vector?: number[];
+    metadata?: M;
+}
+/**
+ * The contract every vector database adapter implements.
+ */
+interface VectorStoreAdapter<M = Record<string, unknown>> {
+    upsert(id: string, vector: number[], metadata?: M): Promise<void>;
+    query(vector: number[], topK: number, filter?: Partial<M>): Promise<VectorMatch<M>[]>;
+    delete(id: string): Promise<void>;
+}
+/**
+ * The names of metric events emitted by cache managers.
+ */
+type MetricEvent = 'cache.hit' | 'cache.miss' | 'cache.set' | 'cache.evict';
+/**
+ * Payload accompanying a metric event.
+ */
+interface MetricData {
+    cacheType: CacheType;
+    latencyMs: number;
+    tokensSaved?: number;
+    estimatedCostUSD?: number;
+    provider?: LLMProvider;
+    model?: string;
+}
+/**
+ * A sink for cache metrics. `@nodellmcache/observability` provides the real
+ * implementation; core ships a no-op so it stays dependency-free.
+ */
+interface MetricsSink {
+    emit(event: MetricEvent, data: MetricData): void;
+}
+/**
+ * Per-call options shared across cache managers.
+ */
+interface CacheOptions {
+    provider?: LLMProvider;
+    model?: string;
+    /** Relative TTL in milliseconds; overrides the manager default. */
+    ttl?: number;
+    /** When false, bypasses the cache entirely (read and write). */
+    cache?: boolean;
+    tokenCount?: number;
+}
+/**
+ * Hit/miss statistics reported by a cache manager.
+ */
+interface CacheStats {
+    hits: number;
+    misses: number;
+    hitRate: number;
+    entryCount: number;
+}
+
+/**
+ * Base class for every error thrown by NodeLLMCache packages. Catching this
+ * catches anything the library throws intentionally.
+ */
+declare class NodeLLMCacheError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown when a storage adapter operation fails. */
+declare class CacheAdapterError extends NodeLLMCacheError {
+}
+/** Thrown when compression or decompression fails. */
+declare class CompressionError extends NodeLLMCacheError {
+}
+/** Thrown when serialization or deserialization fails. */
+declare class SerializationError extends NodeLLMCacheError {
+}
+/** Thrown when a value fails validation (e.g. malformed configuration). */
+declare class ValidationError extends NodeLLMCacheError {
+}
+
+/**
+ * Builds deterministic, collision-resistant cache keys.
+ *
+ * Format: `{type}:{provider}:{model}:{sha256-hash}`
+ *
+ * The raw input text is normalized and hashed with SHA-256 — keys never
+ * contain raw prompt text, which keeps sensitive content out of storage keys
+ * and logs.
+ */
+declare class KeyBuilder {
+    /**
+     * Normalizes text before hashing so trivially different inputs collapse to
+     * the same key: trims surrounding whitespace, lowercases, and collapses any
+     * run of whitespace to a single space.
+     */
+    static normalize(text: string): string;
+    /**
+     * Produces the SHA-256 hex digest of the normalized text.
+     */
+    static hash(text: string): string;
+    /**
+     * Builds a fully namespaced cache key.
+     *
+     * @example
+     * KeyBuilder.build('prompt', 'openai', 'gpt-4o', 'hello world')
+     * // 'prompt:openai:gpt-4o:b94d27b9...'
+     */
+    static build(type: CacheType, provider: LLMProvider | string, model: string, text: string): string;
+}
+
+/**
+ * Centralizes time-to-live arithmetic: computing expiry timestamps, checking
+ * expiry, and supporting sliding-window refresh. All durations are relative
+ * milliseconds; all timestamps are absolute epoch milliseconds.
+ */
+declare class TTLManager {
+    /**
+     * Computes the absolute expiry timestamp for an entry created at `createdAt`
+     * with a relative `ttl`. Returns `undefined` when `ttl` is not a positive
+     * number, meaning the entry never expires.
+     */
+    static computeExpiresAt(createdAt: number, ttl?: number): number | undefined;
+    /**
+     * Returns true when the entry has an expiry and that expiry is at or before
+     * `now` (defaults to the current time).
+     */
+    static isExpired(entry: Pick<CacheEntry<unknown>, 'expiresAt'>, now?: number): boolean;
+    /**
+     * Milliseconds remaining until the entry expires. Returns `Infinity` for
+     * entries with no expiry, and `0` for already-expired entries.
+     */
+    static remaining(entry: Pick<CacheEntry<unknown>, 'expiresAt'>, now?: number): number;
+    /**
+     * Computes a refreshed expiry for a sliding-window TTL: extends the entry's
+     * life by `ttl` from `now`. Returns `undefined` when `ttl` is not positive.
+     */
+    static slide(ttl?: number, now?: number): number | undefined;
+}
+
+/**
+ * Converts values to and from `Buffer` for storage. Implementations decide the
+ * wire format.
+ *
+ * The architecture calls for MessagePack as the primary format, but
+ * `@nodellmcache/core` must stay dependency-free, so it ships only the JSON
+ * implementation below. A MessagePack serializer can be supplied by an optional
+ * package and injected wherever a `Serializer` is accepted.
+ */
+interface Serializer {
+    serialize<T>(value: T): Buffer;
+    deserialize<T>(data: Buffer): T;
+}
+/**
+ * Default JSON-backed serializer. Zero dependencies; handles the common case
+ * and wraps failures in {@link SerializationError}.
+ */
+declare class JsonSerializer implements Serializer {
+    serialize<T>(value: T): Buffer;
+    deserialize<T>(data: Buffer): T;
+}
+
+/** A metrics sink that discards everything; the default when none is injected. */
+declare const noopMetrics: MetricsSink;
+/**
+ * Construction options shared by all cache managers.
+ */
+interface BaseCacheManagerOptions<T> {
+    adapter: StorageAdapter<T>;
+    /** Default relative TTL in milliseconds applied to entries lacking their own. */
+    defaultTTL?: number;
+    /** Metrics sink; defaults to a no-op so core stays dependency-free. */
+    metrics?: MetricsSink;
+}
+/**
+ * Shared base for every feature cache (prompt, embedding, semantic, ...).
+ *
+ * Provides the cache-aside `getOrGenerate` flow, key building, entry
+ * construction, invalidation, and hit/miss accounting. Subclasses declare their
+ * {@link CacheType} and may override {@link buildKey} for custom namespacing.
+ */
+declare abstract class BaseCacheManager<T> {
+    /** The workload category for keys and metrics. */
+    protected abstract readonly cacheType: CacheType;
+    protected readonly adapter: StorageAdapter<T>;
+    protected readonly defaultTTL: number | undefined;
+    protected readonly metrics: MetricsSink;
+    private hits;
+    private misses;
+    constructor(options: BaseCacheManagerOptions<T>);
+    /**
+     * Builds the storage key for an input. Defaults to the canonical
+     * `{type}:{provider}:{model}:{hash}` format via {@link KeyBuilder}.
+     */
+    protected buildKey(input: string, options?: CacheOptions): string;
+    /**
+     * Wraps a value in a {@link CacheEntry} with computed expiry and metadata.
+     */
+    protected buildEntry(key: string, value: T, options?: CacheOptions): CacheEntry<T>;
+    /**
+     * Cache-aside read-through. Returns the cached value on a hit, otherwise
+     * invokes `generator`, stores the result, and returns it. Set
+     * `options.cache = false` to bypass the cache for both read and write.
+     */
+    getOrGenerate(input: string, generator: () => Promise<T>, options?: CacheOptions): Promise<T>;
+    /**
+     * Removes a single entry by its input (and namespacing options).
+     */
+    invalidate(input: string, options?: CacheOptions): Promise<void>;
+    /**
+     * Returns hit/miss accounting for this manager plus the adapter's entry count.
+     */
+    stats(): Promise<CacheStats>;
+}
+
+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

@@ -0,0 +1,316 @@
+/**
+ * The category of data a cache stores. Used in key namespacing and metrics
+ * breakdowns so every cached value is attributable to a workload.
+ */
+type CacheType = 'prompt' | 'embedding' | 'semantic' | 'retrieval' | 'context' | 'agent' | 'tool' | 'conversation';
+/**
+ * Canonical LLM provider names. See the providers table in CLAUDE.md for the
+ * common models associated with each.
+ */
+type LLMProvider = 'openai' | 'anthropic' | 'gemini' | 'deepseek' | 'llama' | 'mistral' | 'ollama';
+/**
+ * Supported compression algorithms. `auto` defers the choice to the
+ * compression engine's size/hint heuristics; `none` is a passthrough.
+ */
+type CompressionAlgo = 'lz4' | 'brotli' | 'zstd' | 'gzip' | 'none' | 'auto';
+/**
+ * A hint describing the shape of a payload so the compression engine can pick
+ * the best codec (e.g. `embedding` favours lz4, `text` favours brotli).
+ */
+type DataHint = 'embedding' | 'text' | 'json' | 'binary';
+
+/**
+ * Metadata stored alongside every cache entry. Captures how the value was
+ * encoded and which LLM workload produced it.
+ */
+interface CacheMetadata {
+    compressed: boolean;
+    compressionAlgo?: CompressionAlgo;
+    originalSize: number;
+    compressedSize?: number;
+    cacheType: CacheType;
+    provider?: LLMProvider;
+    model?: string;
+    tokenCount?: number;
+}
+/**
+ * A single cached value with its bookkeeping. `expiresAt` is an absolute epoch
+ * timestamp in milliseconds; when omitted the entry never expires.
+ */
+interface CacheEntry<T> {
+    key: string;
+    value: T;
+    createdAt: number;
+    expiresAt?: number;
+    metadata: CacheMetadata;
+}
+/**
+ * Aggregate statistics reported by a storage adapter.
+ */
+interface AdapterStats {
+    /** Number of entries currently held. */
+    entryCount: number;
+    /** Approximate bytes used by stored entries, if the adapter can measure it. */
+    sizeBytes?: number;
+    /** Number of evictions performed over the adapter's lifetime. */
+    evictions?: number;
+}
+/**
+ * The contract every storage backend implements. Application code never
+ * imports a concrete adapter in business logic — adapters are injected.
+ */
+interface StorageAdapter<T = unknown> {
+    get(key: string): Promise<CacheEntry<T> | null>;
+    /** `ttl` is a relative duration in milliseconds from now. */
+    set(key: string, entry: CacheEntry<T>, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    stats(): Promise<AdapterStats>;
+}
+/**
+ * Result of a single compression operation.
+ */
+interface CompressedResult {
+    data: Buffer;
+    algo: CompressionAlgo;
+    originalSize: number;
+    compressedSize: number;
+    ratio: number;
+    durationMs: number;
+}
+/**
+ * Statistics for a completed compression, suitable for observability rollups.
+ */
+interface CompressionStats {
+    originalSize: number;
+    compressedSize: number;
+    ratio: number;
+    savedBytes: number;
+    savedPercent: number;
+}
+/**
+ * The compression engine contract implemented by `@nodellmcache/compression`.
+ */
+interface CompressionEngine {
+    compress(data: Buffer, algo: CompressionAlgo): Promise<Buffer>;
+    decompress(data: Buffer, algo: CompressionAlgo): Promise<Buffer>;
+    auto(data: Buffer, hint?: DataHint): Promise<CompressedResult>;
+    stats(original: Buffer, compressed: Buffer): CompressionStats;
+}
+/**
+ * A vector match returned by a vector store query.
+ */
+interface VectorMatch<M = Record<string, unknown>> {
+    id: string;
+    score: number;
+    vector?: number[];
+    metadata?: M;
+}
+/**
+ * The contract every vector database adapter implements.
+ */
+interface VectorStoreAdapter<M = Record<string, unknown>> {
+    upsert(id: string, vector: number[], metadata?: M): Promise<void>;
+    query(vector: number[], topK: number, filter?: Partial<M>): Promise<VectorMatch<M>[]>;
+    delete(id: string): Promise<void>;
+}
+/**
+ * The names of metric events emitted by cache managers.
+ */
+type MetricEvent = 'cache.hit' | 'cache.miss' | 'cache.set' | 'cache.evict';
+/**
+ * Payload accompanying a metric event.
+ */
+interface MetricData {
+    cacheType: CacheType;
+    latencyMs: number;
+    tokensSaved?: number;
+    estimatedCostUSD?: number;
+    provider?: LLMProvider;
+    model?: string;
+}
+/**
+ * A sink for cache metrics. `@nodellmcache/observability` provides the real
+ * implementation; core ships a no-op so it stays dependency-free.
+ */
+interface MetricsSink {
+    emit(event: MetricEvent, data: MetricData): void;
+}
+/**
+ * Per-call options shared across cache managers.
+ */
+interface CacheOptions {
+    provider?: LLMProvider;
+    model?: string;
+    /** Relative TTL in milliseconds; overrides the manager default. */
+    ttl?: number;
+    /** When false, bypasses the cache entirely (read and write). */
+    cache?: boolean;
+    tokenCount?: number;
+}
+/**
+ * Hit/miss statistics reported by a cache manager.
+ */
+interface CacheStats {
+    hits: number;
+    misses: number;
+    hitRate: number;
+    entryCount: number;
+}
+
+/**
+ * Base class for every error thrown by NodeLLMCache packages. Catching this
+ * catches anything the library throws intentionally.
+ */
+declare class NodeLLMCacheError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown when a storage adapter operation fails. */
+declare class CacheAdapterError extends NodeLLMCacheError {
+}
+/** Thrown when compression or decompression fails. */
+declare class CompressionError extends NodeLLMCacheError {
+}
+/** Thrown when serialization or deserialization fails. */
+declare class SerializationError extends NodeLLMCacheError {
+}
+/** Thrown when a value fails validation (e.g. malformed configuration). */
+declare class ValidationError extends NodeLLMCacheError {
+}
+
+/**
+ * Builds deterministic, collision-resistant cache keys.
+ *
+ * Format: `{type}:{provider}:{model}:{sha256-hash}`
+ *
+ * The raw input text is normalized and hashed with SHA-256 — keys never
+ * contain raw prompt text, which keeps sensitive content out of storage keys
+ * and logs.
+ */
+declare class KeyBuilder {
+    /**
+     * Normalizes text before hashing so trivially different inputs collapse to
+     * the same key: trims surrounding whitespace, lowercases, and collapses any
+     * run of whitespace to a single space.
+     */
+    static normalize(text: string): string;
+    /**
+     * Produces the SHA-256 hex digest of the normalized text.
+     */
+    static hash(text: string): string;
+    /**
+     * Builds a fully namespaced cache key.
+     *
+     * @example
+     * KeyBuilder.build('prompt', 'openai', 'gpt-4o', 'hello world')
+     * // 'prompt:openai:gpt-4o:b94d27b9...'
+     */
+    static build(type: CacheType, provider: LLMProvider | string, model: string, text: string): string;
+}
+
+/**
+ * Centralizes time-to-live arithmetic: computing expiry timestamps, checking
+ * expiry, and supporting sliding-window refresh. All durations are relative
+ * milliseconds; all timestamps are absolute epoch milliseconds.
+ */
+declare class TTLManager {
+    /**
+     * Computes the absolute expiry timestamp for an entry created at `createdAt`
+     * with a relative `ttl`. Returns `undefined` when `ttl` is not a positive
+     * number, meaning the entry never expires.
+     */
+    static computeExpiresAt(createdAt: number, ttl?: number): number | undefined;
+    /**
+     * Returns true when the entry has an expiry and that expiry is at or before
+     * `now` (defaults to the current time).
+     */
+    static isExpired(entry: Pick<CacheEntry<unknown>, 'expiresAt'>, now?: number): boolean;
+    /**
+     * Milliseconds remaining until the entry expires. Returns `Infinity` for
+     * entries with no expiry, and `0` for already-expired entries.
+     */
+    static remaining(entry: Pick<CacheEntry<unknown>, 'expiresAt'>, now?: number): number;
+    /**
+     * Computes a refreshed expiry for a sliding-window TTL: extends the entry's
+     * life by `ttl` from `now`. Returns `undefined` when `ttl` is not positive.
+     */
+    static slide(ttl?: number, now?: number): number | undefined;
+}
+
+/**
+ * Converts values to and from `Buffer` for storage. Implementations decide the
+ * wire format.
+ *
+ * The architecture calls for MessagePack as the primary format, but
+ * `@nodellmcache/core` must stay dependency-free, so it ships only the JSON
+ * implementation below. A MessagePack serializer can be supplied by an optional
+ * package and injected wherever a `Serializer` is accepted.
+ */
+interface Serializer {
+    serialize<T>(value: T): Buffer;
+    deserialize<T>(data: Buffer): T;
+}
+/**
+ * Default JSON-backed serializer. Zero dependencies; handles the common case
+ * and wraps failures in {@link SerializationError}.
+ */
+declare class JsonSerializer implements Serializer {
+    serialize<T>(value: T): Buffer;
+    deserialize<T>(data: Buffer): T;
+}
+
+/** A metrics sink that discards everything; the default when none is injected. */
+declare const noopMetrics: MetricsSink;
+/**
+ * Construction options shared by all cache managers.
+ */
+interface BaseCacheManagerOptions<T> {
+    adapter: StorageAdapter<T>;
+    /** Default relative TTL in milliseconds applied to entries lacking their own. */
+    defaultTTL?: number;
+    /** Metrics sink; defaults to a no-op so core stays dependency-free. */
+    metrics?: MetricsSink;
+}
+/**
+ * Shared base for every feature cache (prompt, embedding, semantic, ...).
+ *
+ * Provides the cache-aside `getOrGenerate` flow, key building, entry
+ * construction, invalidation, and hit/miss accounting. Subclasses declare their
+ * {@link CacheType} and may override {@link buildKey} for custom namespacing.
+ */
+declare abstract class BaseCacheManager<T> {
+    /** The workload category for keys and metrics. */
+    protected abstract readonly cacheType: CacheType;
+    protected readonly adapter: StorageAdapter<T>;
+    protected readonly defaultTTL: number | undefined;
+    protected readonly metrics: MetricsSink;
+    private hits;
+    private misses;
+    constructor(options: BaseCacheManagerOptions<T>);
+    /**
+     * Builds the storage key for an input. Defaults to the canonical
+     * `{type}:{provider}:{model}:{hash}` format via {@link KeyBuilder}.
+     */
+    protected buildKey(input: string, options?: CacheOptions): string;
+    /**
+     * Wraps a value in a {@link CacheEntry} with computed expiry and metadata.
+     */
+    protected buildEntry(key: string, value: T, options?: CacheOptions): CacheEntry<T>;
+    /**
+     * Cache-aside read-through. Returns the cached value on a hit, otherwise
+     * invokes `generator`, stores the result, and returns it. Set
+     * `options.cache = false` to bypass the cache for both read and write.
+     */
+    getOrGenerate(input: string, generator: () => Promise<T>, options?: CacheOptions): Promise<T>;
+    /**
+     * Removes a single entry by its input (and namespacing options).
+     */
+    invalidate(input: string, options?: CacheOptions): Promise<void>;
+    /**
+     * Returns hit/miss accounting for this manager plus the adapter's entry count.
+     */
+    stats(): Promise<CacheStats>;
+}
+
+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

@@ -0,0 +1,223 @@
+// src/errors.ts
+var NodeLLMCacheError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = new.target.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var CacheAdapterError = class extends NodeLLMCacheError {
+};
+var CompressionError = class extends NodeLLMCacheError {
+};
+var SerializationError = class extends NodeLLMCacheError {
+};
+var ValidationError = class extends NodeLLMCacheError {
+};
+
+// src/KeyBuilder.ts
+import { createHash } from "crypto";
+var KeyBuilder = class _KeyBuilder {
+  /**
+   * Normalizes text before hashing so trivially different inputs collapse to
+   * the same key: trims surrounding whitespace, lowercases, and collapses any
+   * run of whitespace to a single space.
+   */
+  static normalize(text) {
+    return text.trim().toLowerCase().replace(/\s+/g, " ");
+  }
+  /**
+   * Produces the SHA-256 hex digest of the normalized text.
+   */
+  static hash(text) {
+    return createHash("sha256").update(_KeyBuilder.normalize(text)).digest("hex");
+  }
+  /**
+   * Builds a fully namespaced cache key.
+   *
+   * @example
+   * KeyBuilder.build('prompt', 'openai', 'gpt-4o', 'hello world')
+   * // 'prompt:openai:gpt-4o:b94d27b9...'
+   */
+  static build(type, provider, model, text) {
+    return `${type}:${provider}:${model}:${_KeyBuilder.hash(text)}`;
+  }
+};
+
+// src/TTLManager.ts
+var TTLManager = class _TTLManager {
+  /**
+   * Computes the absolute expiry timestamp for an entry created at `createdAt`
+   * with a relative `ttl`. Returns `undefined` when `ttl` is not a positive
+   * number, meaning the entry never expires.
+   */
+  static computeExpiresAt(createdAt, ttl) {
+    if (ttl === void 0 || ttl <= 0) return void 0;
+    return createdAt + ttl;
+  }
+  /**
+   * Returns true when the entry has an expiry and that expiry is at or before
+   * `now` (defaults to the current time).
+   */
+  static isExpired(entry, now = Date.now()) {
+    return entry.expiresAt !== void 0 && entry.expiresAt <= now;
+  }
+  /**
+   * Milliseconds remaining until the entry expires. Returns `Infinity` for
+   * entries with no expiry, and `0` for already-expired entries.
+   */
+  static remaining(entry, now = Date.now()) {
+    if (entry.expiresAt === void 0) return Infinity;
+    return Math.max(0, entry.expiresAt - now);
+  }
+  /**
+   * Computes a refreshed expiry for a sliding-window TTL: extends the entry's
+   * life by `ttl` from `now`. Returns `undefined` when `ttl` is not positive.
+   */
+  static slide(ttl, now = Date.now()) {
+    return _TTLManager.computeExpiresAt(now, ttl);
+  }
+};
+
+// src/Serializer.ts
+var JsonSerializer = class {
+  serialize(value) {
+    try {
+      return Buffer.from(JSON.stringify(value), "utf8");
+    } catch (cause) {
+      throw new SerializationError("Failed to serialize value to JSON", { cause });
+    }
+  }
+  deserialize(data) {
+    try {
+      return JSON.parse(data.toString("utf8"));
+    } catch (cause) {
+      throw new SerializationError("Failed to deserialize JSON value", { cause });
+    }
+  }
+};
+
+// src/BaseCacheManager.ts
+var noopMetrics = {
+  emit() {
+  }
+};
+var BaseCacheManager = class {
+  adapter;
+  defaultTTL;
+  metrics;
+  hits = 0;
+  misses = 0;
+  constructor(options) {
+    this.adapter = options.adapter;
+    this.defaultTTL = options.defaultTTL;
+    this.metrics = options.metrics ?? noopMetrics;
+  }
+  /**
+   * Builds the storage key for an input. Defaults to the canonical
+   * `{type}:{provider}:{model}:{hash}` format via {@link KeyBuilder}.
+   */
+  buildKey(input, options) {
+    return KeyBuilder.build(
+      this.cacheType,
+      options?.provider ?? "unknown",
+      options?.model ?? "default",
+      input
+    );
+  }
+  /**
+   * Wraps a value in a {@link CacheEntry} with computed expiry and metadata.
+   */
+  buildEntry(key, value, options) {
+    const createdAt = Date.now();
+    const ttl = options?.ttl ?? this.defaultTTL;
+    return {
+      key,
+      value,
+      createdAt,
+      expiresAt: TTLManager.computeExpiresAt(createdAt, ttl),
+      metadata: {
+        compressed: false,
+        originalSize: 0,
+        cacheType: this.cacheType,
+        provider: options?.provider,
+        model: options?.model,
+        tokenCount: options?.tokenCount
+      }
+    };
+  }
+  /**
+   * Cache-aside read-through. Returns the cached value on a hit, otherwise
+   * invokes `generator`, stores the result, and returns it. Set
+   * `options.cache = false` to bypass the cache for both read and write.
+   */
+  async getOrGenerate(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
+      });
+      return cached.value;
+    }
+    this.misses++;
+    this.metrics.emit("cache.miss", {
+      cacheType: this.cacheType,
+      latencyMs: Date.now() - start,
+      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", {
+      cacheType: this.cacheType,
+      latencyMs: Date.now() - start,
+      provider: options?.provider,
+      model: options?.model
+    });
+    return value;
+  }
+  /**
+   * Removes a single entry by its input (and namespacing options).
+   */
+  async invalidate(input, options) {
+    await this.adapter.delete(this.buildKey(input, options));
+  }
+  /**
+   * Returns hit/miss accounting for this manager plus the adapter's entry count.
+   */
+  async stats() {
+    const total = this.hits + this.misses;
+    const adapterStats = await this.adapter.stats();
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total === 0 ? 0 : this.hits / total,
+      entryCount: adapterStats.entryCount
+    };
+  }
+};
+export {
+  BaseCacheManager,
+  CacheAdapterError,
+  CompressionError,
+  JsonSerializer,
+  KeyBuilder,
+  NodeLLMCacheError,
+  SerializationError,
+  TTLManager,
+  ValidationError,
+  noopMetrics
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +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":";AAIO,IAAM,oBAAN,cAAgC,MAAM;AAAA,EAC3C,YAAY,SAAiB,SAAwB;AACnD,UAAM,SAAS,OAAO;AACtB,SAAK,OAAO,WAAW;AAEvB,WAAO,eAAe,MAAM,WAAW,SAAS;AAAA,EAClD;AACF;AAGO,IAAM,oBAAN,cAAgC,kBAAkB;AAAC;AAGnD,IAAM,mBAAN,cAA+B,kBAAkB;AAAC;AAGlD,IAAM,qBAAN,cAAiC,kBAAkB;AAAC;AAGpD,IAAM,kBAAN,cAA8B,kBAAkB;AAAC;;;ACvBxD,SAAS,kBAAkB;AAYpB,IAAM,aAAN,MAAM,YAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMtB,OAAO,UAAU,MAAsB;AACrC,WAAO,KAAK,KAAK,EAAE,YAAY,EAAE,QAAQ,QAAQ,GAAG;AAAA,EACtD;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,KAAK,MAAsB;AAChC,WAAO,WAAW,QAAQ,EAAE,OAAO,YAAW,UAAU,IAAI,CAAC,EAAE,OAAO,KAAK;AAAA,EAC7E;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,OAAO,MACL,MACA,UACA,OACA,MACQ;AACR,WAAO,GAAG,IAAI,IAAI,QAAQ,IAAI,KAAK,IAAI,YAAW,KAAK,IAAI,CAAC;AAAA,EAC9D;AACF;;;ACrCO,IAAM,aAAN,MAAM,YAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMtB,OAAO,iBAAiB,WAAmB,KAAkC;AAC3E,QAAI,QAAQ,UAAa,OAAO,EAAG,QAAO;AAC1C,WAAO,YAAY;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAO,UAAU,OAA+C,MAAc,KAAK,IAAI,GAAY;AACjG,WAAO,MAAM,cAAc,UAAa,MAAM,aAAa;AAAA,EAC7D;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAO,UAAU,OAA+C,MAAc,KAAK,IAAI,GAAW;AAChG,QAAI,MAAM,cAAc,OAAW,QAAO;AAC1C,WAAO,KAAK,IAAI,GAAG,MAAM,YAAY,GAAG;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAO,MAAM,KAAc,MAAc,KAAK,IAAI,GAAuB;AACvE,WAAO,YAAW,iBAAiB,KAAK,GAAG;AAAA,EAC7C;AACF;;;ACtBO,IAAM,iBAAN,MAA2C;AAAA,EAChD,UAAa,OAAkB;AAC7B,QAAI;AACF,aAAO,OAAO,KAAK,KAAK,UAAU,KAAK,GAAG,MAAM;AAAA,IAClD,SAAS,OAAO;AACd,YAAM,IAAI,mBAAmB,qCAAqC,EAAE,MAAM,CAAC;AAAA,IAC7E;AAAA,EACF;AAAA,EAEA,YAAe,MAAiB;AAC9B,QAAI;AACF,aAAO,KAAK,MAAM,KAAK,SAAS,MAAM,CAAC;AAAA,IACzC,SAAS,OAAO;AACd,YAAM,IAAI,mBAAmB,oCAAoC,EAAE,MAAM,CAAC;AAAA,IAC5E;AAAA,EACF;AACF;;;ACxBO,IAAM,cAA2B;AAAA,EACtC,OAAO;AAAA,EAEP;AACF;AAoBO,IAAe,mBAAf,MAAmC;AAAA,EAIrB;AAAA,EACA;AAAA,EACA;AAAA,EAEX,OAAO;AAAA,EACP,SAAS;AAAA,EAEjB,YAAY,SAAqC;AAC/C,SAAK,UAAU,QAAQ;AACvB,SAAK,aAAa,QAAQ;AAC1B,SAAK,UAAU,QAAQ,WAAW;AAAA,EACpC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMU,SAAS,OAAe,SAAgC;AAChE,WAAO,WAAW;AAAA,MAChB,KAAK;AAAA,MACL,SAAS,YAAY;AAAA,MACrB,SAAS,SAAS;AAAA,MAClB;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKU,WAAW,KAAa,OAAU,SAAuC;AACjF,UAAM,YAAY,KAAK,IAAI;AAC3B,UAAM,MAAM,SAAS,OAAO,KAAK;AACjC,WAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,MACA,WAAW,WAAW,iBAAiB,WAAW,GAAG;AAAA,MACrD,UAAU;AAAA,QACR,YAAY;AAAA,QACZ,cAAc;AAAA,QACd,WAAW,KAAK;AAAA,QAChB,UAAU,SAAS;AAAA,QACnB,OAAO,SAAS;AAAA,QAChB,YAAY,SAAS;AAAA,MACvB;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,cACJ,OACA,WACA,SACY;AAGZ,QAAI,SAAS,UAAU,OAAO;AAC5B,aAAO,UAAU;AAAA,IACnB;AAEA,UAAM,MAAM,KAAK,SAAS,OAAO,OAAO;AACxC,UAAM,QAAQ,KAAK,IAAI;AAEvB,UAAM,SAAS,MAAM,KAAK,QAAQ,IAAI,GAAG;AACzC,QAAI,UAAU,CAAC,WAAW,UAAU,MAAM,GAAG;AAC3C,WAAK;AACL,WAAK,QAAQ,KAAK,aAAa;AAAA,QAC7B,WAAW,KAAK;AAAA,QAChB,WAAW,KAAK,IAAI,IAAI;AAAA,QACxB,aAAa,OAAO,SAAS;AAAA,QAC7B,UAAU,SAAS;AAAA,QACnB,OAAO,SAAS;AAAA,MAClB,CAAC;AACD,aAAO,OAAO;AAAA,IAChB;AAEA,SAAK;AACL,SAAK,QAAQ,KAAK,cAAc;AAAA,MAC9B,WAAW,KAAK;AAAA,MAChB,WAAW,KAAK,IAAI,IAAI;AAAA,MACxB,UAAU,SAAS;AAAA,MACnB,OAAO,SAAS;AAAA,IAClB,CAAC;AAED,UAAM,QAAQ,MAAM,UAAU;AAE9B,UAAM,MAAM,SAAS,OAAO,KAAK;AACjC,UAAM,QAAQ,KAAK,WAAW,KAAK,OAAO,OAAO;AACjD,UAAM,KAAK,QAAQ,IAAI,KAAK,OAAO,GAAG;AACtC,SAAK,QAAQ,KAAK,aAAa;AAAA,MAC7B,WAAW,KAAK;AAAA,MAChB,WAAW,KAAK,IAAI,IAAI;AAAA,MACxB,UAAU,SAAS;AAAA,MACnB,OAAO,SAAS;AAAA,IAClB,CAAC;AAED,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,WAAW,OAAe,SAAuC;AACrE,UAAM,KAAK,QAAQ,OAAO,KAAK,SAAS,OAAO,OAAO,CAAC;AAAA,EACzD;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,QAA6B;AACjC,UAAM,QAAQ,KAAK,OAAO,KAAK;AAC/B,UAAM,eAAe,MAAM,KAAK,QAAQ,MAAM;AAC9C,WAAO;AAAA,MACL,MAAM,KAAK;AAAA,MACX,QAAQ,KAAK;AAAA,MACb,SAAS,UAAU,IAAI,IAAI,KAAK,OAAO;AAAA,MACvC,YAAY,aAAa;AAAA,IAC3B;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@nodellmcache/core",
+  "version": "0.1.0",
+  "description": "Shared interfaces, types, and utilities for NodeLLMCache — AI memory infrastructure for Node.js",
+  "keywords": ["llm", "cache", "ai", "memory", "nodejs", "embeddings"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdmax007/node-llm-cache.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/mdmax007/node-llm-cache/tree/main/packages/core#readme",
+  "bugs": "https://github.com/mdmax007/node-llm-cache/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "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\""
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "@vitest/coverage-v8": "^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}