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

package/README.md

@@ -27,3 +27,5 @@ are deduplicated, translated once in source order, cached, and restored to their
 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

@@ -113,9 +113,38 @@ 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 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?.({
@@ -142,7 +171,7 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
       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 +198,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

@@ -87,9 +87,38 @@ 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 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?.({
@@ -116,7 +145,7 @@ function withTranslationCache(baseAdapter, cache, options = {}) {
       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 +172,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.0",
   "publishConfig": {
     "access": "public"
   },
@@ -38,7 +38,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@form-engine-ts/core": "2.8.0"
+    "@form-engine-ts/core": "2.9.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean --external @form-engine-ts/core",