i18n-keyless-node 1.12.3 → 1.12.5

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { init, getTranslation, getAllTranslationsForAllLanguages, awaitForTranslation } from "./service";
+export { init, getAllTranslationsForAllLanguages, awaitForTranslation } from "./service";
 export type { Translations, I18nKeylessNodeConfig, I18nKeylessNodeStore, TranslationOptions, I18nKeylessRequestBody, I18nKeylessAllTranslationsResponse, } from "./types";
 export { type Lang, type PrimaryLang, type I18nKeylessResponse, queue } from "i18n-keyless-core";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { init, getTranslation, getAllTranslationsForAllLanguages, awaitForTranslation } from "./service";
+export { init, getAllTranslationsForAllLanguages, awaitForTranslation } from "./service";
 export { queue } from "i18n-keyless-core";

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "i18n-keyless-node",
     "private": false,
-    "version": "1.12.3",
+    "version": "1.12.5",
     "type": "module",
     "main": "./dist/index.js",
     "module": "./dist/index.js",
@@ -15,7 +15,7 @@
         "postpublish": "rm -rf ./dist && rm *.tgz"
     },
     "dependencies": {
-        "i18n-keyless-core": "1.12.3"
+        "i18n-keyless-core": "1.12.5"
     },
     "devDependencies": {
         "@eslint/js": "^9.9.0",

package/dist/service.d.ts

@@ -1,18 +1,37 @@
 import { type Lang, type TranslationOptions, I18nKeylessAllTranslationsResponse } from "i18n-keyless-core";
-import { I18nKeylessNodeConfig, I18nKeylessNodeStore } from "types";
+import { I18nKeylessNodeConfig } from "types";
 /**
  * Fetches all translations
  * @param store - The translation store
  * @returns Promise resolving to the translation response or void if failed
  */
-export declare function getAllTranslationsForAllLanguages(store: I18nKeylessNodeStore): Promise<I18nKeylessAllTranslationsResponse | void>;
+export declare function getAllTranslationsForAllLanguages(): Promise<I18nKeylessAllTranslationsResponse | void>;
 export declare function init(newConfig: I18nKeylessNodeConfig): Promise<I18nKeylessNodeConfig>;
-export declare function getTranslation(key: string, currentLanguage: Lang, options?: TranslationOptions): string;
 /**
- * Queues a key for translation if not already translated
+ * Core logic for fetching/retrieving a translation asynchronously.
  * @param key - The text to translate
- * @param store - The translation store
+ * @param currentLanguage - The language to translate to
+ * @param options - Optional parameters for the translation process
+ * @returns Promise resolving to the translated string or the original key
+ */
+declare function awaitForTranslationFn(key: string, currentLanguage: Lang, options?: TranslationOptions): Promise<string>;
+/**
+ * **MANDATORY AWAIT / PROMISE HANDLING REQUIRED IN NODE.JS**
+ *
+ * Asynchronously retrieves a translation for a key, fetching from the backend if necessary.
+ * In a Node.js environment, failure to `await` this function inside a `try...catch` block
+ * or attach a `.catch()` handler WILL lead to an unhandled promise rejection if an error
+ * occurs during translation (e.g., network error, API error). This unhandled rejection
+ * is designed to cause a **FATAL ERROR** and **CRASH** the Node.js process to prevent
+ * silent failures. Ensure all calls are properly handled.
+ *
+ * **Recommendation:** Use the `@typescript-eslint/no-floating-promises` lint rule.
+ *
+ * @param key - The text to translate
+ * @param currentLanguage - The language to translate to
  * @param options - Optional parameters for the translation process
- * @throws Error if config is not initialized
+ * @returns A Promise resolving to the translated string or the original key if not found/on error *after handling*.
+ * @throws Re-throws any internal error if the promise rejection is not handled by the caller.
  */
-export declare const awaitForTranslation: (key: string, currentLanguage: Lang, options?: TranslationOptions) => Promise<string>;
+export declare const awaitForTranslation: typeof awaitForTranslationFn;
+export {};

package/dist/service.js

@@ -1,4 +1,4 @@
-import { queue, getTranslationCore, api, } from "i18n-keyless-core";
+import { queue, api, } from "i18n-keyless-core";
 import packageJson from "./package.json";
 const store = {
     translations: {
@@ -34,7 +34,7 @@ const store = {
  * @param store - The translation store
  * @returns Promise resolving to the translation response or void if failed
  */
-export async function getAllTranslationsForAllLanguages(store) {
+export async function getAllTranslationsForAllLanguages() {
     const config = store.config;
     const lastRefresh = store.lastRefresh;
     const uniqueId = store.uniqueId;
@@ -73,7 +73,7 @@ export async function getAllTranslationsForAllLanguages(store) {
 }
 queue.on("empty", () => {
     // when each word is translated, fetch the translations for the current language
-    getAllTranslationsForAllLanguages(store).then((res) => {
+    getAllTranslationsForAllLanguages().then((res) => {
         if (res?.ok) {
             store.translations = res.data.translations;
         }
@@ -96,110 +96,158 @@ export async function init(newConfig) {
     newConfig.addMissingTranslations = true;
     store.config = newConfig;
     store.config.onInit?.(newConfig.languages.primary);
-    const response = await getAllTranslationsForAllLanguages(store);
+    const response = await getAllTranslationsForAllLanguages();
     if (response?.ok) {
         store.translations = response.data.translations;
     }
     return newConfig;
 }
-export function getTranslation(key, currentLanguage, options) {
-    if (options?.debug) {
-        console.log("getTranslation", key, currentLanguage, store.translations);
-    }
-    return getTranslationCore(key, {
-        ...store,
-        config: store.config,
-        currentLanguage,
-        translations: store.translations[currentLanguage],
-    }, options);
-}
 /**
- * Queues a key for translation if not already translated
+ * Core logic for fetching/retrieving a translation asynchronously.
  * @param key - The text to translate
- * @param store - The translation store
+ * @param currentLanguage - The language to translate to
  * @param options - Optional parameters for the translation process
- * @throws Error if config is not initialized
+ * @returns Promise resolving to the translated string or the original key
  */
-export const awaitForTranslation = new Proxy(async function (key, currentLanguage, options) {
+async function awaitForTranslationFn(key, currentLanguage, options) {
+    const config = store.config;
+    const translations = store.translations;
+    const uniqueId = store.uniqueId;
+    const context = options?.context;
+    const debug = options?.debug;
     try {
-        const config = store.config;
-        const translations = store.translations;
-        const uniqueId = store.uniqueId;
-        if (!config.API_KEY) {
-            throw new Error("i18n-keyless: config is not initialized");
+        // Ensure config is initialized enough for either API call or custom handler
+        if (!config.API_KEY && !config.handleTranslate) {
+            throw new Error("i18n-keyless: config lacks API_KEY and handleTranslate. Cannot proceed.");
         }
-        const context = options?.context;
-        const debug = options?.debug;
-        // if (key.length > 280) {
-        //   console.error("i18n-keyless: Key length exceeds 280 characters limit:", key);
-        //   return;
-        // }
         if (!key) {
             return "";
         }
         if (debug) {
-            console.log("translateKey", key, context, debug);
+            console.log("i18n-keyless: awaitForTranslationFn called with:", { key, currentLanguage, context, options });
         }
         const forceTemporaryLang = options?.forceTemporary?.[currentLanguage];
-        const translation = context
-            ? translations[currentLanguage][`${key}__${context}`]
-            : translations[currentLanguage][key];
+        const translationKey = context ? `${key}__${context}` : key;
+        // Safe navigation for potentially undefined language store
+        const translation = translations[currentLanguage]?.[translationKey];
+        // Return existing translation if found and not forced temporary
         if (translation && !forceTemporaryLang) {
             if (debug) {
-                console.log("translation exists", `${key}__${context}`);
+                console.log(`i18n-keyless: Translation found in store for key: "${translationKey}"`);
             }
             return translation;
         }
+        // Use custom handler if provided
         if (config.handleTranslate) {
-            await config.handleTranslate?.(key);
-        }
-        else {
-            const body = {
-                key,
-                context,
-                forceTemporary: options?.forceTemporary,
-                languages: config.languages.supported,
-                primaryLanguage: config.languages.primary,
-            };
-            const apiUrl = config.API_URL || "https://api.i18n-keyless.com";
-            const url = `${apiUrl}/translate?return_translation=true`;
             if (debug) {
-                console.log("fetching translation", url, body);
+                console.log(`i18n-keyless: Using handleTranslate for key: "${key}"`);
             }
-            const response = await api
-                .fetchTranslation(url, {
-                method: "POST",
-                headers: {
-                    "Content-Type": "application/json",
-                    Authorization: `Bearer ${config.API_KEY}`,
-                    unique_id: uniqueId || "",
-                    Version: packageJson.version,
-                },
-                body: JSON.stringify(body),
-            })
-                .then((res) => res);
-            if (debug) {
-                console.log("response", response);
+            // Expect handleTranslate to manage its own errors/state updates
+            await config.handleTranslate(key); // Pass only the key
+            // Re-check store after custom handler, maybe it populated the translation
+            const updatedTranslation = translations[currentLanguage]?.[translationKey];
+            if (updatedTranslation) {
+                if (debug) {
+                    console.log(`i18n-keyless: Translation found for key "${translationKey}" after handleTranslate`);
+                }
+                return updatedTranslation;
             }
-            if (response.message) {
-                console.warn("i18n-keyless: ", response.message);
+            // If still not found after custom handler, return original key
+            if (debug) {
+                console.warn(`i18n-keyless: Translation for key "${translationKey}" still not found after handleTranslate.`);
             }
-            return response.data || key;
+            return key;
         }
+        // Proceed with API call if no custom handler
+        if (!config.API_KEY) {
+            // This should technically be caught earlier, but belt-and-suspenders
+            throw new Error("i18n-keyless: API_KEY is required for API translation but missing.");
+        }
+        const body = {
+            key,
+            context,
+            forceTemporary: options?.forceTemporary,
+            languages: config.languages.supported,
+            primaryLanguage: config.languages.primary,
+        };
+        const apiUrl = config.API_URL || "https://api.i18n-keyless.com";
+        const url = `${apiUrl}/translate`;
+        if (debug) {
+            console.log("i18n-keyless: Fetching translation from API:", { url, body });
+        }
+        const response = await api
+            .fetchTranslation(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${config.API_KEY}`,
+                unique_id: uniqueId || "",
+                Version: packageJson.version,
+            },
+            body: JSON.stringify(body),
+        })
+            .then((res) => res);
+        if (debug) {
+            console.log("i18n-keyless: API response received:", response);
+        }
+        if (!response.ok) {
+            // Throw an error if the API response indicates failure
+            throw new Error(response.error || `i18n-keyless: API request failed for key "${key}"`);
+        }
+        if (response.message) {
+            // Log any informational messages from the API
+            console.warn("i18n-keyless: API message:", response.message);
+        }
+        // Return the fetched translation or the original key if not available for the current language
+        const fetchedTranslation = response.data?.translation?.[currentLanguage];
+        if (debug && !fetchedTranslation) {
+            console.log(`i18n-keyless: Translation for lang "${currentLanguage}" not found in API response for key "${key}". Returning original key.`);
+        }
+        return fetchedTranslation || key;
     }
     catch (error) {
-        console.error("i18n-keyless: Error await translating key:", error);
+        // Log the specific error during translation attempt
+        console.error(`i18n-keyless: Error during awaitForTranslationFn for key "${key}":`, error);
+        // Re-throw the error to ensure the promise returned by this async function rejects
+        throw error;
     }
-    return key;
-}, {
+}
+/**
+ * **MANDATORY AWAIT / PROMISE HANDLING REQUIRED IN NODE.JS**
+ *
+ * Asynchronously retrieves a translation for a key, fetching from the backend if necessary.
+ * In a Node.js environment, failure to `await` this function inside a `try...catch` block
+ * or attach a `.catch()` handler WILL lead to an unhandled promise rejection if an error
+ * occurs during translation (e.g., network error, API error). This unhandled rejection
+ * is designed to cause a **FATAL ERROR** and **CRASH** the Node.js process to prevent
+ * silent failures. Ensure all calls are properly handled.
+ *
+ * **Recommendation:** Use the `@typescript-eslint/no-floating-promises` lint rule.
+ *
+ * @param key - The text to translate
+ * @param currentLanguage - The language to translate to
+ * @param options - Optional parameters for the translation process
+ * @returns A Promise resolving to the translated string or the original key if not found/on error *after handling*.
+ * @throws Re-throws any internal error if the promise rejection is not handled by the caller.
+ */
+export const awaitForTranslation = new Proxy(awaitForTranslationFn, // Target the named async function
+{
     apply(target, thisArg, args) {
-        const result = Reflect.apply(target, thisArg, args);
-        if (result instanceof Promise) {
-            result.catch((error) => {
-                console.error("awaitForTranslation was not properly awaited:", error);
-                throw error;
-            });
-        }
-        return result;
+        // Call the actual async function
+        const promise = Reflect.apply(target, thisArg, args);
+        // Attach a catch handler. This runs ONLY if the promise REJECTS.
+        promise.catch((error) => {
+            // Log a specific error message indicating an unhandled rejection.
+            console.error(`i18n-keyless: FATAL: Unhandled rejection in awaitForTranslation! ` +
+                `The promise for key "${String(args[0])}" was rejected and not caught. ` +
+                `Ensure the call is wrapped in try/catch and awaited, or attach a .catch() handler. ` +
+                `Original error:`, error);
+            // Re-throw the error. In Node.js, an uncaught promise rejection
+            // will typically terminate the process (depending on Node version and handlers).
+            // This enforces handling of translation errors.
+            throw error;
+        });
+        // Return the original promise to the caller
+        return promise;
     },
 });

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import { Lang, PrimaryLang } from "i18n-keyless-core";
+import { HandleTranslateFunction, Lang, PrimaryLang } from "i18n-keyless-core";
 export type Translations = Record<string, string>;
 export interface I18nKeylessNodeConfig {
     /**
@@ -54,10 +54,7 @@ export interface I18nKeylessNodeConfig {
      * - not use this `handleTranslate` function, and use the built in API call with API_KEY filled
      * - not use this `handleTranslate` function nor API_KEY key, and provide your own API_URL
      */
-    handleTranslate?: (key: string) => Promise<{
-        ok: boolean;
-        message: string;
-    }>;
+    handleTranslate?: HandleTranslateFunction;
     /**
      * if this function exists, it will be called instead of the API call
      * if this function doesn't exist, the default behavior is to call the API, with the API_KEY

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "i18n-keyless-node",
   "private": false,
-  "version": "1.12.3",
+  "version": "1.12.5",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -15,7 +15,7 @@
     "postpublish": "rm -rf ./dist && rm *.tgz"
   },
   "dependencies": {
-    "i18n-keyless-core": "1.12.3"
+    "i18n-keyless-core": "1.12.5"
   },
   "devDependencies": {
     "@eslint/js": "^9.9.0",