@form-engine-ts/translator-cache 2.7.0 → 2.9.0

package/README.md

@@ -25,3 +25,7 @@ const translator = withTranslationCache(baseTranslator, cache, {
 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.
+Cache backend failures default to `cacheErrorPolicy: "bypass"`: `onCacheError` is notified and translation continues
+through the wrapped adapter. Use `cacheErrorPolicy: "throw"` when cache availability is mandatory.

package/dist/index.cjs

@@ -107,14 +107,73 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
   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.");
+  }
+  if (options.cacheErrorPolicy !== void 0 && options.cacheErrorPolicy !== "bypass" && options.cacheErrorPolicy !== "throw") {
+    throw new TypeError('cacheErrorPolicy must be "bypass" or "throw".');
+  }
+  const cacheErrorPolicy = options.cacheErrorPolicy ?? "bypass";
+  const initialEvictionCount = cache.evictionCount ?? 0;
+  let hits = 0;
+  let misses = 0;
+  const handleCacheError = (cause, operation) => {
+    const error = cause instanceof Error ? cause : new Error(String(cause));
+    try {
+      options.onCacheError?.(error, operation);
+    } catch {
+    }
+    return error;
+  };
+  const getCached = async (key) => {
+    try {
+      return await cache.get(key);
+    } catch (cause) {
+      const error = handleCacheError(cause, "get");
+      if (cacheErrorPolicy === "throw") throw error;
+      return void 0;
+    }
+  };
+  const setCached = async (key, value) => {
+    try {
+      await cache.set(key, value, options.ttlMs);
+    } catch (cause) {
+      const error = handleCacheError(cause, "set");
+      if (cacheErrorPolicy === "throw") throw error;
+    }
+  };
+  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}:${adapterName}:${source}:${target}:${hashTranslationText(text)}`);
-    const cached = await Promise.all(keys.map((key) => cache.get(key)));
+    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(getCached));
+    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;
@@ -139,15 +198,17 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
         missing.map(async ([key, value], translatedIndex) => {
           const translation = translated[translatedIndex];
           if (translation === void 0) throw new Error("Translation adapter result is unavailable.");
-          await cache.set(key, translation, options.ttlMs);
+          await setCached(key, translation);
           for (const index of value.indices) cached[index] = translation;
         })
       );
     }
-    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) {

package/dist/index.d.cts

@@ -1,13 +1,32 @@
 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;
+    readonly cacheErrorPolicy?: "bypass" | "throw";
+    readonly onCacheError?: (error: Error, operation: "get" | "set") => void;
 }
 interface MemoryTranslationCacheOptions {
     readonly maxEntries?: number;
@@ -23,4 +42,4 @@ declare function hashTranslationText(text: string): string;
 declare function createMemoryTranslationCache(options?: MemoryTranslationCacheOptions): MemoryTranslationCache;
 declare function withTranslationCache(baseAdapter: AsyncTranslationAdapter, cache: TranslationCacheStorage, options?: TranslationCacheOptions): AsyncTranslationAdapter;
 
-export { type MemoryTranslationCache, type MemoryTranslationCacheOptions, type TranslationCacheOptions, type TranslationCacheStorage, createMemoryTranslationCache, hashTranslationText, withTranslationCache };
+export { type MemoryTranslationCache, type MemoryTranslationCacheOptions, type TranslationCacheKeyContext, type TranslationCacheOptions, type TranslationCacheStats, type TranslationCacheStorage, createMemoryTranslationCache, hashTranslationText, withTranslationCache };

package/dist/index.d.ts

@@ -1,13 +1,32 @@
 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;
+    readonly cacheErrorPolicy?: "bypass" | "throw";
+    readonly onCacheError?: (error: Error, operation: "get" | "set") => void;
 }
 interface MemoryTranslationCacheOptions {
     readonly maxEntries?: number;
@@ -23,4 +42,4 @@ declare function hashTranslationText(text: string): string;
 declare function createMemoryTranslationCache(options?: MemoryTranslationCacheOptions): MemoryTranslationCache;
 declare function withTranslationCache(baseAdapter: AsyncTranslationAdapter, cache: TranslationCacheStorage, options?: TranslationCacheOptions): AsyncTranslationAdapter;
 
-export { type MemoryTranslationCache, type MemoryTranslationCacheOptions, type TranslationCacheOptions, type TranslationCacheStorage, createMemoryTranslationCache, hashTranslationText, withTranslationCache };
+export { type MemoryTranslationCache, type MemoryTranslationCacheOptions, type TranslationCacheKeyContext, type TranslationCacheOptions, type TranslationCacheStats, type TranslationCacheStorage, createMemoryTranslationCache, hashTranslationText, withTranslationCache };

package/dist/index.js

@@ -81,14 +81,73 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
   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.");
+  }
+  if (options.cacheErrorPolicy !== void 0 && options.cacheErrorPolicy !== "bypass" && options.cacheErrorPolicy !== "throw") {
+    throw new TypeError('cacheErrorPolicy must be "bypass" or "throw".');
+  }
+  const cacheErrorPolicy = options.cacheErrorPolicy ?? "bypass";
+  const initialEvictionCount = cache.evictionCount ?? 0;
+  let hits = 0;
+  let misses = 0;
+  const handleCacheError = (cause, operation) => {
+    const error = cause instanceof Error ? cause : new Error(String(cause));
+    try {
+      options.onCacheError?.(error, operation);
+    } catch {
+    }
+    return error;
+  };
+  const getCached = async (key) => {
+    try {
+      return await cache.get(key);
+    } catch (cause) {
+      const error = handleCacheError(cause, "get");
+      if (cacheErrorPolicy === "throw") throw error;
+      return void 0;
+    }
+  };
+  const setCached = async (key, value) => {
+    try {
+      await cache.set(key, value, options.ttlMs);
+    } catch (cause) {
+      const error = handleCacheError(cause, "set");
+      if (cacheErrorPolicy === "throw") throw error;
+    }
+  };
+  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}:${adapterName}:${source}:${target}:${hashTranslationText(text)}`);
-    const cached = await Promise.all(keys.map((key) => cache.get(key)));
+    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(getCached));
+    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;
@@ -113,15 +172,17 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
         missing.map(async ([key, value], translatedIndex) => {
           const translation = translated[translatedIndex];
           if (translation === void 0) throw new Error("Translation adapter result is unavailable.");
-          await cache.set(key, translation, options.ttlMs);
+          await setCached(key, translation);
           for (const index of value.indices) cached[index] = translation;
         })
       );
     }
-    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) {

package/package.json

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