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

package/README.md

@@ -12,13 +12,16 @@ 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.

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,13 +105,15 @@ 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.");
   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) => `${prefix}:${adapterName}:${source}:${target}:${hashTranslationText(text)}`);
     const cached = await Promise.all(keys.map((key) => cache.get(key)));
     const missingByKey = /* @__PURE__ */ new Map();
     for (let index = 0; index < texts.length; index += 1) {
@@ -104,6 +161,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

@@ -7,8 +7,20 @@ interface TranslationCacheStorage {
 interface TranslationCacheOptions {
     readonly ttlMs?: number;
     readonly keyPrefix?: string;
+    readonly adapterName?: string;
+}
+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 TranslationCacheOptions, type TranslationCacheStorage, createMemoryTranslationCache, hashTranslationText, withTranslationCache };

package/dist/index.d.ts

@@ -7,8 +7,20 @@ interface TranslationCacheStorage {
 interface TranslationCacheOptions {
     readonly ttlMs?: number;
     readonly keyPrefix?: string;
+    readonly adapterName?: string;
+}
+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 TranslationCacheOptions, 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,13 +79,15 @@ 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.");
   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) => `${prefix}:${adapterName}:${source}:${target}:${hashTranslationText(text)}`);
     const cached = await Promise.all(keys.map((key) => cache.get(key)));
     const missingByKey = /* @__PURE__ */ new Map();
     for (let index = 0; index < texts.length; index += 1) {
@@ -78,6 +134,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.7.0",
   "publishConfig": {
     "access": "public"
   },
@@ -38,7 +38,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@form-engine-ts/core": "2.6.0"
+    "@form-engine-ts/core": "2.7.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean --external @form-engine-ts/core",