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

package/README.md

@@ -26,4 +26,8 @@ Keys isolate adapter name, source locale, target locale, and a deterministic UTF
 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.
+Adapters that expose a locale-aware cache variant (such as `@form-engine-ts/translator-google-v3` with a glossary)
+are isolated automatically; an explicit `variant` is combined with that adapter variant.
 `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

@@ -48,6 +48,11 @@ function nonNegativeDuration(value, fallback, name) {
   }
   return resolved;
 }
+function getVariantProvider(adapter) {
+  if (typeof adapter !== "object" || adapter === null) return void 0;
+  const candidate = adapter;
+  return typeof candidate.getCacheVariant === "function" ? { getCacheVariant: candidate.getCacheVariant.bind(adapter) } : void 0;
+}
 function createMemoryTranslationCache(options = {}) {
   const maxEntries = options.maxEntries ?? 500;
   if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
@@ -113,9 +118,39 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
   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 variantProvider = getVariantProvider(baseAdapter);
+  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?.({
@@ -131,18 +166,23 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
     }
     const target = requireLocale(targetLocale, "targetLocale");
     const source = sourceLocale === void 0 ? "auto" : requireLocale(sourceLocale, "sourceLocale");
+    const automaticVariant = variantProvider?.getCacheVariant(target, sourceLocale);
+    if (automaticVariant !== void 0 && automaticVariant.trim().length === 0) {
+      throw new TypeError("baseAdapter cache variant must not be empty.");
+    }
+    const variant = options.variant === void 0 ? automaticVariant : automaticVariant === void 0 ? options.variant : `${options.variant}:${automaticVariant}`;
     const keys = texts.map((text) => {
       const context = {
         sourceText: text,
         sourceLocale: source,
         targetLocale: target,
-        ...options.variant === void 0 ? {} : { variant: options.variant }
+        ...variant === void 0 ? {} : { variant }
       };
-      const key = options.buildKey?.(context) ?? `${prefix}:${adapterName}:${options.variant === void 0 ? "" : `${options.variant}:`}${source}:${target}:${hashTranslationText(text)}`;
+      const key = options.buildKey?.(context) ?? `${prefix}:${adapterName}:${variant === void 0 ? "" : `${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)));
+    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();
@@ -169,7 +209,7 @@ 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;
         })
       );

package/dist/index.d.cts

@@ -25,6 +25,8 @@ interface TranslationCacheOptions {
     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;

package/dist/index.d.ts

@@ -25,6 +25,8 @@ interface TranslationCacheOptions {
     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;

package/dist/index.js

@@ -22,6 +22,11 @@ function nonNegativeDuration(value, fallback, name) {
   }
   return resolved;
 }
+function getVariantProvider(adapter) {
+  if (typeof adapter !== "object" || adapter === null) return void 0;
+  const candidate = adapter;
+  return typeof candidate.getCacheVariant === "function" ? { getCacheVariant: candidate.getCacheVariant.bind(adapter) } : void 0;
+}
 function createMemoryTranslationCache(options = {}) {
   const maxEntries = options.maxEntries ?? 500;
   if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
@@ -87,9 +92,39 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
   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 variantProvider = getVariantProvider(baseAdapter);
+  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?.({
@@ -105,18 +140,23 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
     }
     const target = requireLocale(targetLocale, "targetLocale");
     const source = sourceLocale === void 0 ? "auto" : requireLocale(sourceLocale, "sourceLocale");
+    const automaticVariant = variantProvider?.getCacheVariant(target, sourceLocale);
+    if (automaticVariant !== void 0 && automaticVariant.trim().length === 0) {
+      throw new TypeError("baseAdapter cache variant must not be empty.");
+    }
+    const variant = options.variant === void 0 ? automaticVariant : automaticVariant === void 0 ? options.variant : `${options.variant}:${automaticVariant}`;
     const keys = texts.map((text) => {
       const context = {
         sourceText: text,
         sourceLocale: source,
         targetLocale: target,
-        ...options.variant === void 0 ? {} : { variant: options.variant }
+        ...variant === void 0 ? {} : { variant }
       };
-      const key = options.buildKey?.(context) ?? `${prefix}:${adapterName}:${options.variant === void 0 ? "" : `${options.variant}:`}${source}:${target}:${hashTranslationText(text)}`;
+      const key = options.buildKey?.(context) ?? `${prefix}:${adapterName}:${variant === void 0 ? "" : `${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)));
+    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();
@@ -143,7 +183,7 @@ 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;
         })
       );

package/package.json

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