@form-engine-ts/translator-cache 2.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 form-engine-ts contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @form-engine-ts/translator-cache
+
+Cache decorator for any `AsyncTranslationAdapter`. Cache storage is injected, so applications can use memory, Redis,
+durable edge storage, or another TTL-capable backend without coupling the package to a vendor.
+
+## Install
+
+```bash
+pnpm add @form-engine-ts/core @form-engine-ts/translator-cache
+```
+
+## Usage
+
+```ts
+import { withTranslationCache } from "@form-engine-ts/translator-cache";
+
+const translator = withTranslationCache(baseTranslator, cacheStorage, {
+  ttlMs: 60 * 60 * 1000,
+  keyPrefix: "survey-translations"
+});
+```
+
+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.

package/dist/index.cjs

@@ -0,0 +1,109 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  hashTranslationText: () => hashTranslationText,
+  withTranslationCache: () => withTranslationCache
+});
+module.exports = __toCommonJS(index_exports);
+var FNV_OFFSET_BASIS = 14695981039346656037n;
+var FNV_PRIME = 1099511628211n;
+var UINT64_MASK = 0xffffffffffffffffn;
+function hashTranslationText(text) {
+  if (typeof text !== "string") throw new TypeError("text must be a string.");
+  let hash = FNV_OFFSET_BASIS;
+  for (const byte of new TextEncoder().encode(text)) {
+    hash ^= BigInt(byte);
+    hash = hash * FNV_PRIME & UINT64_MASK;
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+function requireLocale(value, name) {
+  if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`${name} must not be empty.`);
+  return value.trim();
+}
+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") {
+    throw new TypeError("cache must implement get and set.");
+  }
+  if (options.ttlMs !== void 0 && (!Number.isSafeInteger(options.ttlMs) || options.ttlMs < 0)) {
+    throw new TypeError("ttlMs must be a non-negative safe integer.");
+  }
+  const prefix = options.keyPrefix ?? "form-engine-ts";
+  if (prefix.trim().length === 0) throw new TypeError("keyPrefix 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 cached = await Promise.all(keys.map((key) => cache.get(key)));
+    const missingByKey = /* @__PURE__ */ new Map();
+    for (let index = 0; index < texts.length; index += 1) {
+      if (cached[index] !== void 0) continue;
+      const key = keys[index];
+      const text = texts[index];
+      if (key === void 0 || text === void 0) throw new Error("Translation cache index is unavailable.");
+      const missing = missingByKey.get(key);
+      if (missing === void 0) missingByKey.set(key, { text, indices: [index] });
+      else missing.indices.push(index);
+    }
+    if (missingByKey.size > 0) {
+      const missing = [...missingByKey.entries()];
+      const translated = await baseAdapter.translateBatch(
+        missing.map(([, value]) => value.text),
+        target,
+        sourceLocale
+      );
+      if (translated.length !== missing.length) {
+        throw new Error(`Translation adapter returned ${translated.length} values for ${missing.length} cache misses.`);
+      }
+      await Promise.all(
+        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);
+          for (const index of value.indices) cached[index] = translation;
+        })
+      );
+    }
+    return cached.map((value) => {
+      if (value === void 0) throw new Error("Translation cache result is unavailable.");
+      return value;
+    });
+  };
+  return {
+    async translateText(text, targetLocale, sourceLocale) {
+      const translated = await translateBatch([text], targetLocale, sourceLocale);
+      const value = translated[0];
+      if (value === void 0) throw new Error("Translation cache returned no translation.");
+      return value;
+    },
+    translateBatch
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  hashTranslationText,
+  withTranslationCache
+});

package/dist/index.d.cts

@@ -0,0 +1,14 @@
+import { AsyncTranslationAdapter } from '@form-engine-ts/core';
+
+interface TranslationCacheStorage {
+    get(key: string): Promise<string | undefined> | string | undefined;
+    set(key: string, value: string, ttlMs?: number): Promise<void> | void;
+}
+interface TranslationCacheOptions {
+    readonly ttlMs?: number;
+    readonly keyPrefix?: string;
+}
+declare function hashTranslationText(text: string): string;
+declare function withTranslationCache(baseAdapter: AsyncTranslationAdapter, cache: TranslationCacheStorage, options?: TranslationCacheOptions): AsyncTranslationAdapter;
+
+export { type TranslationCacheOptions, type TranslationCacheStorage, hashTranslationText, withTranslationCache };

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { AsyncTranslationAdapter } from '@form-engine-ts/core';
+
+interface TranslationCacheStorage {
+    get(key: string): Promise<string | undefined> | string | undefined;
+    set(key: string, value: string, ttlMs?: number): Promise<void> | void;
+}
+interface TranslationCacheOptions {
+    readonly ttlMs?: number;
+    readonly keyPrefix?: string;
+}
+declare function hashTranslationText(text: string): string;
+declare function withTranslationCache(baseAdapter: AsyncTranslationAdapter, cache: TranslationCacheStorage, options?: TranslationCacheOptions): AsyncTranslationAdapter;
+
+export { type TranslationCacheOptions, type TranslationCacheStorage, hashTranslationText, withTranslationCache };

package/dist/index.js

@@ -0,0 +1,83 @@
+// src/index.ts
+var FNV_OFFSET_BASIS = 14695981039346656037n;
+var FNV_PRIME = 1099511628211n;
+var UINT64_MASK = 0xffffffffffffffffn;
+function hashTranslationText(text) {
+  if (typeof text !== "string") throw new TypeError("text must be a string.");
+  let hash = FNV_OFFSET_BASIS;
+  for (const byte of new TextEncoder().encode(text)) {
+    hash ^= BigInt(byte);
+    hash = hash * FNV_PRIME & UINT64_MASK;
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+function requireLocale(value, name) {
+  if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`${name} must not be empty.`);
+  return value.trim();
+}
+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") {
+    throw new TypeError("cache must implement get and set.");
+  }
+  if (options.ttlMs !== void 0 && (!Number.isSafeInteger(options.ttlMs) || options.ttlMs < 0)) {
+    throw new TypeError("ttlMs must be a non-negative safe integer.");
+  }
+  const prefix = options.keyPrefix ?? "form-engine-ts";
+  if (prefix.trim().length === 0) throw new TypeError("keyPrefix 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 cached = await Promise.all(keys.map((key) => cache.get(key)));
+    const missingByKey = /* @__PURE__ */ new Map();
+    for (let index = 0; index < texts.length; index += 1) {
+      if (cached[index] !== void 0) continue;
+      const key = keys[index];
+      const text = texts[index];
+      if (key === void 0 || text === void 0) throw new Error("Translation cache index is unavailable.");
+      const missing = missingByKey.get(key);
+      if (missing === void 0) missingByKey.set(key, { text, indices: [index] });
+      else missing.indices.push(index);
+    }
+    if (missingByKey.size > 0) {
+      const missing = [...missingByKey.entries()];
+      const translated = await baseAdapter.translateBatch(
+        missing.map(([, value]) => value.text),
+        target,
+        sourceLocale
+      );
+      if (translated.length !== missing.length) {
+        throw new Error(`Translation adapter returned ${translated.length} values for ${missing.length} cache misses.`);
+      }
+      await Promise.all(
+        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);
+          for (const index of value.indices) cached[index] = translation;
+        })
+      );
+    }
+    return cached.map((value) => {
+      if (value === void 0) throw new Error("Translation cache result is unavailable.");
+      return value;
+    });
+  };
+  return {
+    async translateText(text, targetLocale, sourceLocale) {
+      const translated = await translateBatch([text], targetLocale, sourceLocale);
+      const value = translated[0];
+      if (value === void 0) throw new Error("Translation cache returned no translation.");
+      return value;
+    },
+    translateBatch
+  };
+}
+export {
+  hashTranslationText,
+  withTranslationCache
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@form-engine-ts/translator-cache",
+  "version": "2.6.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nitta-a/form-engine-ts.git",
+    "directory": "packages/translator-cache"
+  },
+  "bugs": {
+    "url": "https://github.com/nitta-a/form-engine-ts/issues"
+  },
+  "homepage": "https://github.com/nitta-a/form-engine-ts#readme",
+  "keywords": [
+    "form",
+    "translation",
+    "cache",
+    "typescript"
+  ],
+  "dependencies": {
+    "@form-engine-ts/core": "2.6.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --external @form-engine-ts/core",
+    "check": "biome check . && tsc --noEmit",
+    "test": "vitest run --globals",
+    "typecheck": "tsc --noEmit"
+  }
+}