@form-engine-ts/translator-cache 2.6.0 → 2.8.0

package/README.md

@@ -12,13 +12,18 @@ pnpm add @form-engine-ts/core @form-engine-ts/translator-cache
 ## Usage
 
 ```ts
-import { withTranslationCache } from "@form-engine-ts/translator-cache";
+import { createMemoryTranslationCache, withTranslationCache } from "@form-engine-ts/translator-cache";
 
-const translator = withTranslationCache(baseTranslator, cacheStorage, {
+const cache = createMemoryTranslationCache({ maxEntries: 500, ttlMs: 5 * 60 * 1000 });
+const translator = withTranslationCache(baseTranslator, cache, {
   ttlMs: 60 * 60 * 1000,
-  keyPrefix: "survey-translations"
+  keyPrefix: "survey-translations",
+  adapterName: "google-v3"
 });
 ```
 
-Keys isolate source locale, target locale, and a deterministic UTF-8 hash of the source text. Batch misses are deduplicated,
-translated once in source order, cached, and restored to their original positions.
+Keys isolate adapter name, source locale, target locale, and a deterministic UTF-8 hash of the source text. Batch misses
+are deduplicated, translated once in source order, cached, and restored to their original positions. The built-in memory
+cache applies both TTL expiration and bounded LRU eviction and exposes `size`, `evictionCount`, and `clear()` diagnostics.
+Use `variant` to isolate glossary/model/configuration revisions, or `buildKey` for complete key control.
+`onStatsReport` receives cumulative real cache hits, misses, evictions, and current size after successful translations.

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  createMemoryTranslationCache: () => createMemoryTranslationCache,
   hashTranslationText: () => hashTranslationText,
   withTranslationCache: () => withTranslationCache
 });
@@ -40,6 +41,60 @@ function requireLocale(value, name) {
   if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`${name} must not be empty.`);
   return value.trim();
 }
+function nonNegativeDuration(value, fallback, name) {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved < 0) {
+    throw new TypeError(`${name} must be a non-negative safe integer.`);
+  }
+  return resolved;
+}
+function createMemoryTranslationCache(options = {}) {
+  const maxEntries = options.maxEntries ?? 500;
+  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+    throw new TypeError("maxEntries must be a positive safe integer.");
+  }
+  const defaultTtlMs = nonNegativeDuration(options.ttlMs, 5 * 60 * 1e3, "ttlMs");
+  const now = options.now ?? Date.now;
+  const entries = /* @__PURE__ */ new Map();
+  let evictionCount = 0;
+  const evictExpired = (key, entry) => {
+    if (entry.expiresAt > now()) return false;
+    entries.delete(key);
+    evictionCount += 1;
+    return true;
+  };
+  return {
+    get size() {
+      for (const [key, entry] of entries) evictExpired(key, entry);
+      return entries.size;
+    },
+    get evictionCount() {
+      return evictionCount;
+    },
+    get(key) {
+      const entry = entries.get(key);
+      if (entry === void 0 || evictExpired(key, entry)) return void 0;
+      entries.delete(key);
+      entries.set(key, entry);
+      return entry.value;
+    },
+    set(key, value, ttlMs) {
+      const resolvedTtlMs = nonNegativeDuration(ttlMs, defaultTtlMs, "ttlMs");
+      if (!entries.has(key) && entries.size >= maxEntries) {
+        const leastRecentlyUsed = entries.keys().next().value;
+        if (leastRecentlyUsed !== void 0) {
+          entries.delete(leastRecentlyUsed);
+          evictionCount += 1;
+        }
+      }
+      entries.delete(key);
+      entries.set(key, { value, expiresAt: now() + resolvedTtlMs });
+    },
+    clear() {
+      entries.clear();
+    }
+  };
+}
 function withTranslationCache(baseAdapter, cache, options = {}) {
   if (typeof baseAdapter?.translateBatch !== "function") throw new TypeError("baseAdapter.translateBatch is required.");
   if (typeof cache?.get !== "function" || typeof cache.set !== "function") {
@@ -50,14 +105,46 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
   }
   const prefix = options.keyPrefix ?? "form-engine-ts";
   if (prefix.trim().length === 0) throw new TypeError("keyPrefix must not be empty.");
+  const adapterName = options.adapterName ?? "anonymous";
+  if (adapterName.trim().length === 0) throw new TypeError("adapterName must not be empty.");
+  if (options.variant !== void 0 && options.variant.trim().length === 0) {
+    throw new TypeError("variant must not be empty.");
+  }
+  if (options.buildKey !== void 0 && typeof options.buildKey !== "function") {
+    throw new TypeError("buildKey must be a function.");
+  }
+  const initialEvictionCount = cache.evictionCount ?? 0;
+  let hits = 0;
+  let misses = 0;
+  const reportStats = () => {
+    const size = cache.size ?? 0;
+    options.onStatsReport?.({
+      hits,
+      misses,
+      evictions: Math.max(0, (cache.evictionCount ?? initialEvictionCount) - initialEvictionCount),
+      size
+    });
+  };
   const translateBatch = async (texts, targetLocale, sourceLocale) => {
     if (!Array.isArray(texts) || texts.some((text) => typeof text !== "string")) {
       throw new TypeError("texts must be an array of strings.");
     }
     const target = requireLocale(targetLocale, "targetLocale");
     const source = sourceLocale === void 0 ? "auto" : requireLocale(sourceLocale, "sourceLocale");
-    const keys = texts.map((text) => `${prefix}:${source}:${target}:${hashTranslationText(text)}`);
+    const keys = texts.map((text) => {
+      const context = {
+        sourceText: text,
+        sourceLocale: source,
+        targetLocale: target,
+        ...options.variant === void 0 ? {} : { variant: options.variant }
+      };
+      const key = options.buildKey?.(context) ?? `${prefix}:${adapterName}:${options.variant === void 0 ? "" : `${options.variant}:`}${source}:${target}:${hashTranslationText(text)}`;
+      if (typeof key !== "string" || key.length === 0) throw new TypeError("Translation cache key must not be empty.");
+      return key;
+    });
     const cached = await Promise.all(keys.map((key) => cache.get(key)));
+    hits += cached.filter((value) => value !== void 0).length;
+    misses += cached.filter((value) => value === void 0).length;
     const missingByKey = /* @__PURE__ */ new Map();
     for (let index = 0; index < texts.length; index += 1) {
       if (cached[index] !== void 0) continue;
@@ -87,10 +174,12 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
         })
       );
     }
-    return cached.map((value) => {
+    const result = cached.map((value) => {
       if (value === void 0) throw new Error("Translation cache result is unavailable.");
       return value;
     });
+    reportStats();
+    return result;
   };
   return {
     async translateText(text, targetLocale, sourceLocale) {
@@ -104,6 +193,7 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  createMemoryTranslationCache,
   hashTranslationText,
   withTranslationCache
 });

package/dist/index.d.cts

@@ -1,14 +1,43 @@
 import { AsyncTranslationAdapter } from '@form-engine-ts/core';
 
 interface TranslationCacheStorage {
+    readonly size?: number;
+    readonly evictionCount?: number;
     get(key: string): Promise<string | undefined> | string | undefined;
     set(key: string, value: string, ttlMs?: number): Promise<void> | void;
 }
+interface TranslationCacheKeyContext {
+    readonly sourceText: string;
+    readonly sourceLocale: string;
+    readonly targetLocale: string;
+    readonly variant?: string;
+}
+interface TranslationCacheStats {
+    readonly hits: number;
+    readonly misses: number;
+    readonly evictions: number;
+    readonly size: number;
+}
 interface TranslationCacheOptions {
     readonly ttlMs?: number;
     readonly keyPrefix?: string;
+    readonly adapterName?: string;
+    readonly variant?: string;
+    readonly buildKey?: (context: TranslationCacheKeyContext) => string;
+    readonly onStatsReport?: (stats: TranslationCacheStats) => void;
+}
+interface MemoryTranslationCacheOptions {
+    readonly maxEntries?: number;
+    readonly ttlMs?: number;
+    readonly now?: () => number;
+}
+interface MemoryTranslationCache extends TranslationCacheStorage {
+    readonly size: number;
+    readonly evictionCount: number;
+    clear(): void;
 }
 declare function hashTranslationText(text: string): string;
+declare function createMemoryTranslationCache(options?: MemoryTranslationCacheOptions): MemoryTranslationCache;
 declare function withTranslationCache(baseAdapter: AsyncTranslationAdapter, cache: TranslationCacheStorage, options?: TranslationCacheOptions): AsyncTranslationAdapter;
 
-export { type TranslationCacheOptions, type TranslationCacheStorage, hashTranslationText, withTranslationCache };
+export { type MemoryTranslationCache, type MemoryTranslationCacheOptions, type TranslationCacheKeyContext, type TranslationCacheOptions, type TranslationCacheStats, type TranslationCacheStorage, createMemoryTranslationCache, hashTranslationText, withTranslationCache };

package/dist/index.d.ts

@@ -1,14 +1,43 @@
 import { AsyncTranslationAdapter } from '@form-engine-ts/core';
 
 interface TranslationCacheStorage {
+    readonly size?: number;
+    readonly evictionCount?: number;
     get(key: string): Promise<string | undefined> | string | undefined;
     set(key: string, value: string, ttlMs?: number): Promise<void> | void;
 }
+interface TranslationCacheKeyContext {
+    readonly sourceText: string;
+    readonly sourceLocale: string;
+    readonly targetLocale: string;
+    readonly variant?: string;
+}
+interface TranslationCacheStats {
+    readonly hits: number;
+    readonly misses: number;
+    readonly evictions: number;
+    readonly size: number;
+}
 interface TranslationCacheOptions {
     readonly ttlMs?: number;
     readonly keyPrefix?: string;
+    readonly adapterName?: string;
+    readonly variant?: string;
+    readonly buildKey?: (context: TranslationCacheKeyContext) => string;
+    readonly onStatsReport?: (stats: TranslationCacheStats) => void;
+}
+interface MemoryTranslationCacheOptions {
+    readonly maxEntries?: number;
+    readonly ttlMs?: number;
+    readonly now?: () => number;
+}
+interface MemoryTranslationCache extends TranslationCacheStorage {
+    readonly size: number;
+    readonly evictionCount: number;
+    clear(): void;
 }
 declare function hashTranslationText(text: string): string;
+declare function createMemoryTranslationCache(options?: MemoryTranslationCacheOptions): MemoryTranslationCache;
 declare function withTranslationCache(baseAdapter: AsyncTranslationAdapter, cache: TranslationCacheStorage, options?: TranslationCacheOptions): AsyncTranslationAdapter;
 
-export { type TranslationCacheOptions, type TranslationCacheStorage, hashTranslationText, withTranslationCache };
+export { type MemoryTranslationCache, type MemoryTranslationCacheOptions, type TranslationCacheKeyContext, type TranslationCacheOptions, type TranslationCacheStats, type TranslationCacheStorage, createMemoryTranslationCache, hashTranslationText, withTranslationCache };

package/dist/index.js

@@ -15,6 +15,60 @@ function requireLocale(value, name) {
   if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`${name} must not be empty.`);
   return value.trim();
 }
+function nonNegativeDuration(value, fallback, name) {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved < 0) {
+    throw new TypeError(`${name} must be a non-negative safe integer.`);
+  }
+  return resolved;
+}
+function createMemoryTranslationCache(options = {}) {
+  const maxEntries = options.maxEntries ?? 500;
+  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+    throw new TypeError("maxEntries must be a positive safe integer.");
+  }
+  const defaultTtlMs = nonNegativeDuration(options.ttlMs, 5 * 60 * 1e3, "ttlMs");
+  const now = options.now ?? Date.now;
+  const entries = /* @__PURE__ */ new Map();
+  let evictionCount = 0;
+  const evictExpired = (key, entry) => {
+    if (entry.expiresAt > now()) return false;
+    entries.delete(key);
+    evictionCount += 1;
+    return true;
+  };
+  return {
+    get size() {
+      for (const [key, entry] of entries) evictExpired(key, entry);
+      return entries.size;
+    },
+    get evictionCount() {
+      return evictionCount;
+    },
+    get(key) {
+      const entry = entries.get(key);
+      if (entry === void 0 || evictExpired(key, entry)) return void 0;
+      entries.delete(key);
+      entries.set(key, entry);
+      return entry.value;
+    },
+    set(key, value, ttlMs) {
+      const resolvedTtlMs = nonNegativeDuration(ttlMs, defaultTtlMs, "ttlMs");
+      if (!entries.has(key) && entries.size >= maxEntries) {
+        const leastRecentlyUsed = entries.keys().next().value;
+        if (leastRecentlyUsed !== void 0) {
+          entries.delete(leastRecentlyUsed);
+          evictionCount += 1;
+        }
+      }
+      entries.delete(key);
+      entries.set(key, { value, expiresAt: now() + resolvedTtlMs });
+    },
+    clear() {
+      entries.clear();
+    }
+  };
+}
 function withTranslationCache(baseAdapter, cache, options = {}) {
   if (typeof baseAdapter?.translateBatch !== "function") throw new TypeError("baseAdapter.translateBatch is required.");
   if (typeof cache?.get !== "function" || typeof cache.set !== "function") {
@@ -25,14 +79,46 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
   }
   const prefix = options.keyPrefix ?? "form-engine-ts";
   if (prefix.trim().length === 0) throw new TypeError("keyPrefix must not be empty.");
+  const adapterName = options.adapterName ?? "anonymous";
+  if (adapterName.trim().length === 0) throw new TypeError("adapterName must not be empty.");
+  if (options.variant !== void 0 && options.variant.trim().length === 0) {
+    throw new TypeError("variant must not be empty.");
+  }
+  if (options.buildKey !== void 0 && typeof options.buildKey !== "function") {
+    throw new TypeError("buildKey must be a function.");
+  }
+  const initialEvictionCount = cache.evictionCount ?? 0;
+  let hits = 0;
+  let misses = 0;
+  const reportStats = () => {
+    const size = cache.size ?? 0;
+    options.onStatsReport?.({
+      hits,
+      misses,
+      evictions: Math.max(0, (cache.evictionCount ?? initialEvictionCount) - initialEvictionCount),
+      size
+    });
+  };
   const translateBatch = async (texts, targetLocale, sourceLocale) => {
     if (!Array.isArray(texts) || texts.some((text) => typeof text !== "string")) {
       throw new TypeError("texts must be an array of strings.");
     }
     const target = requireLocale(targetLocale, "targetLocale");
     const source = sourceLocale === void 0 ? "auto" : requireLocale(sourceLocale, "sourceLocale");
-    const keys = texts.map((text) => `${prefix}:${source}:${target}:${hashTranslationText(text)}`);
+    const keys = texts.map((text) => {
+      const context = {
+        sourceText: text,
+        sourceLocale: source,
+        targetLocale: target,
+        ...options.variant === void 0 ? {} : { variant: options.variant }
+      };
+      const key = options.buildKey?.(context) ?? `${prefix}:${adapterName}:${options.variant === void 0 ? "" : `${options.variant}:`}${source}:${target}:${hashTranslationText(text)}`;
+      if (typeof key !== "string" || key.length === 0) throw new TypeError("Translation cache key must not be empty.");
+      return key;
+    });
     const cached = await Promise.all(keys.map((key) => cache.get(key)));
+    hits += cached.filter((value) => value !== void 0).length;
+    misses += cached.filter((value) => value === void 0).length;
     const missingByKey = /* @__PURE__ */ new Map();
     for (let index = 0; index < texts.length; index += 1) {
       if (cached[index] !== void 0) continue;
@@ -62,10 +148,12 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
         })
       );
     }
-    return cached.map((value) => {
+    const result = cached.map((value) => {
       if (value === void 0) throw new Error("Translation cache result is unavailable.");
       return value;
     });
+    reportStats();
+    return result;
   };
   return {
     async translateText(text, targetLocale, sourceLocale) {
@@ -78,6 +166,7 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
   };
 }
 export {
+  createMemoryTranslationCache,
   hashTranslationText,
   withTranslationCache
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/translator-cache",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "publishConfig": {
     "access": "public"
   },
@@ -38,7 +38,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@form-engine-ts/core": "2.6.0"
+    "@form-engine-ts/core": "2.8.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean --external @form-engine-ts/core",