@digitaldefiance/i18n-lib 1.0.22 → 1.0.24

package/dist/src/i18n-engine.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.I18nEngine = void 0;
+const context_1 = require("./context");
+const enum_registry_1 = require("./enum-registry");
+const template_1 = require("./template");
+const utils_1 = require("./utils");
+/**
+ * Internationalization engine class
+ */
+class I18nEngine {
+    /**
+     * Creates a new I18nEngine instance
+     * @param config The i18n configuration
+     * @param key Optional instance key for the semi-singleton pattern
+     * @throws Error if an instance with the same key already exists
+     */
+    constructor(config, key, newContext = () => (0, context_1.createContext)(config.defaultLanguage, config.defaultTranslationContext, config.defaultCurrencyCode, config.timezone, config.adminTimezone)) {
+        this.config = config;
+        this.enumRegistry = new enum_registry_1.EnumTranslationRegistry();
+        this._context = newContext();
+        const instanceKey = key || I18nEngine.DefaultInstanceKey;
+        if (I18nEngine._instances.has(instanceKey)) {
+            const existing = I18nEngine._instances.get(instanceKey);
+            throw new Error(existing.translate('Error_InstanceAlreadyExistsTemplate', {
+                key: instanceKey,
+            }));
+        }
+        I18nEngine._instances.set(instanceKey, this);
+        if (!I18nEngine._defaultKey) {
+            I18nEngine._defaultKey = instanceKey;
+        }
+        // Initialize the default template processor
+        this.t = (0, template_1.createTemplateProcessor)(this.config.enumObj || {}, (key, vars, language) => this.translate(key, vars, language), this.config.enumName || 'StringKey');
+    }
+    /**
+     * Gets an instance of the I18nEngine by key. If no key is provided, the default instance is returned.
+     * @param key The key of the instance to retrieve
+     * @returns The I18nEngine instance
+     * @throws Error if the instance with the provided key does not exist
+     */
+    static getInstance(key) {
+        const instanceKey = key || I18nEngine._defaultKey || I18nEngine.DefaultInstanceKey;
+        if (!instanceKey || !I18nEngine._instances.has(instanceKey)) {
+            throw new Error(I18nEngine.getErrorMessage('Error_InstanceNotFoundTemplate', {
+                key: instanceKey,
+            }));
+        }
+        return I18nEngine._instances.get(instanceKey);
+    }
+    /**
+     * Gets a translation for the provided error key using the specified instance (or default instance if none is provided).
+     * @param errorKey The error key to translate
+     * @param vars Variables to replace in the translation string
+     * @param instanceKey The key of the I18nEngine instance to use
+     * @param language The language to translate to
+     * @param fallbackLanguage The fallback language if the translation is not found
+     * @returns The translated error message
+     */
+    static getErrorMessage(errorKey, vars, instanceKey, language, fallbackLanguage) {
+        try {
+            const instance = I18nEngine.getInstance(instanceKey);
+            return instance.translate(errorKey, vars, language, fallbackLanguage);
+        }
+        catch {
+            return `${errorKey}: ${JSON.stringify(vars || {})}`;
+        }
+    }
+    /**
+     * Throws an error with a translated message using the specified instance (or default instance if none is provided).
+     * @param errorKey The error key to translate
+     * @param vars Variables to replace in the translation string
+     * @param instanceKey The key of the I18nEngine instance to use
+     * @throws Error with translated message
+     */
+    static throwError(errorKey, vars, instanceKey) {
+        throw new Error(I18nEngine.getErrorMessage(errorKey, vars, instanceKey));
+    }
+    /**
+     * Gets the global context for translations
+     * @returns The global context object
+     */
+    get context() {
+        return this._context;
+    }
+    /**
+     * Sets the global context for translations (used if no context is provided) for this instance
+     * @param context The context to set
+     */
+    set context(context) {
+        this._context = { ...this._context, ...context };
+    }
+    /**
+     * Translates a string key into the specified language, replacing any variables as needed.
+     * @param key The string key to translate
+     * @param vars Variables to replace in the translation string
+     * @param language The language to translate to
+     * @param fallbackLanguage The fallback language if the translation is not found
+     * @returns The translated string
+     */
+    translate(key, vars, language, fallbackLanguage) {
+        const lang = language ??
+            (this._context.currentContext === 'admin'
+                ? this._context.adminLanguage
+                : this._context.language);
+        const fallback = fallbackLanguage ?? this.config.defaultLanguage;
+        try {
+            const stringValue = this.getString(lang, key);
+            return (0, utils_1.isTemplate)(key)
+                ? (0, utils_1.replaceVariables)(stringValue, vars, this.config.constants)
+                : stringValue;
+        }
+        catch {
+            if (lang !== fallback) {
+                try {
+                    const stringValue = this.getString(fallback, key);
+                    return (0, utils_1.isTemplate)(key)
+                        ? (0, utils_1.replaceVariables)(stringValue, vars, this.config.constants)
+                        : stringValue;
+                }
+                catch {
+                    return key;
+                }
+            }
+            return key;
+        }
+    }
+    /**
+     * Translates an enumeration value into the specified language.
+     * @param enumObj The enumeration object
+     * @param value The enumeration value to translate
+     * @param language The language to translate to
+     * @returns The translated enumeration value
+     */
+    translateEnum(enumObj, value, language) {
+        return this.enumRegistry.translate(enumObj, value, language);
+    }
+    /**
+     * Registers an enumeration and its translations with the engine.
+     * @param enumObj The enumeration object
+     * @param translations The translations for the enumeration
+     * @param enumName The name of the enumeration (for error messages)
+     */
+    registerEnum(enumObj, translations, enumName) {
+        this.enumRegistry.register(enumObj, translations, enumName);
+    }
+    /**
+     * Safe translation that prevents infinite recursion for error messages
+     * @param key The string key to translate
+     * @param vars Variables to replace in the translation string
+     * @param language The language to translate to
+     * @returns The translated string or the key if translation fails
+     */
+    safeTranslate(key, vars, language) {
+        try {
+            const lang = language ?? this.config.defaultLanguage;
+            const strings = this.config.strings[lang];
+            if (!strings?.[key])
+                return key;
+            const stringValue = strings[key];
+            return (0, utils_1.isTemplate)(key)
+                ? (0, utils_1.replaceVariables)(stringValue, vars, this.config.constants)
+                : stringValue;
+        }
+        catch {
+            return key;
+        }
+    }
+    /**
+     * Retrieves the string for the given language and key, throwing an error if not found.
+     * @param language The language to get the string for
+     * @param key The string key to retrieve
+     * @returns The string value
+     * @throws Error if the language or string key is not found
+     */
+    getString(language, key) {
+        const strings = this.config.strings[language];
+        if (!strings) {
+            throw new Error(this.safeTranslate('Error_LanguageNotFound', { language }) ||
+                `Language not found: ${language}`);
+        }
+        const value = strings[key];
+        if (!value) {
+            throw new Error(this.safeTranslate('Error_StringNotFound', { key }) ||
+                `String not found: ${key}`);
+        }
+        return value;
+    }
+    /**
+     * Gets the language code for the specified language.
+     * @param language The language to get the code for
+     * @returns The language code
+     */
+    getLanguageCode(language) {
+        return this.config.languageCodes[language] || language;
+    }
+    /**
+     * Gets the language for the specified language code.
+     * @param code The language code to look up
+     * @returns The language, or undefined if not found
+     */
+    getLanguageFromCode(code) {
+        for (const [lang, langCode] of Object.entries(this.config.languageCodes)) {
+            if (langCode === code) {
+                return lang;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Gets all language codes.
+     * @returns A record of all language codes
+     */
+    getAllLanguageCodes() {
+        return this.config.languageCodes;
+    }
+    /**
+     * Gets all available languages.
+     * @returns An array of all available languages
+     */
+    getAvailableLanguages() {
+        return Object.keys(this.config.strings);
+    }
+    /**
+     * Checks if a language is available.
+     * @param language The language to check
+     * @returns True if the language is available, false otherwise
+     */
+    isLanguageAvailable(language) {
+        return Object.keys(this.config.strings).includes(language);
+    }
+    /**
+     * Clears all instances (for testing purposes)
+     * @internal
+     */
+    static clearInstances() {
+        I18nEngine._instances.clear();
+        I18nEngine._defaultKey = null;
+    }
+    /**
+     * Removes a specific instance by key
+     * @param key The key of the instance to remove
+     * @internal
+     */
+    static removeInstance(key) {
+        const instanceKey = key || I18nEngine.DefaultInstanceKey;
+        I18nEngine._instances.delete(instanceKey);
+        if (I18nEngine._defaultKey === instanceKey) {
+            const nextKey = I18nEngine._instances.keys().next().value;
+            I18nEngine._defaultKey =
+                I18nEngine._instances.size > 0 && nextKey ? nextKey : null;
+        }
+    }
+}
+exports.I18nEngine = I18nEngine;
+/**
+ * Static instances for semi-singleton pattern
+ */
+I18nEngine._instances = new Map();
+/**
+ * Default instance key (first created instance)
+ */
+I18nEngine._defaultKey = null;
+/**
+ * Default instance key if none is provided
+ */
+I18nEngine.DefaultInstanceKey = 'default';

package/dist/src/index.d.ts

@@ -0,0 +1,13 @@
+export * from './active-context';
+export * from './context';
+export * from './context-manager';
+export * from './currency';
+export * from './currency-code';
+export * from './currency-format';
+export * from './enum-registry';
+export * from './i18n-engine';
+export * from './template';
+export * from './timezone';
+export * from './types';
+export * from './utils';
+export { I18nEngine as I18n } from './i18n-engine';

package/dist/src/index.js

@@ -0,0 +1,32 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.I18n = void 0;
+__exportStar(require("./active-context"), exports);
+__exportStar(require("./context"), exports);
+__exportStar(require("./context-manager"), exports);
+__exportStar(require("./currency"), exports);
+__exportStar(require("./currency-code"), exports);
+__exportStar(require("./currency-format"), exports);
+__exportStar(require("./enum-registry"), exports);
+__exportStar(require("./i18n-engine"), exports);
+__exportStar(require("./template"), exports);
+__exportStar(require("./timezone"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./utils"), exports);
+// Re-export for convenience
+var i18n_engine_1 = require("./i18n-engine");
+Object.defineProperty(exports, "I18n", { enumerable: true, get: function () { return i18n_engine_1.I18nEngine; } });

package/dist/src/template.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Template processing utilities for i18n
+ */
+export type EnumKeys<T> = keyof T;
+/**
+ * Recursive type to validate that all enum keys in the template string exist in the provided enum type
+ */
+export type IsValidEnumTemplate<T extends string, TEnum> = T extends `${string}{{${string}.${infer Key}}}${infer Rest}` ? Key extends EnumKeys<TEnum> ? IsValidEnumTemplate<Rest, TEnum> : false : true;
+/**
+ * Template function that processes {{EnumName.EnumKey}} patterns
+ */
+export declare function createTemplateProcessor<TEnum extends Record<string, string>, TLanguage extends string>(enumObj: TEnum, translateFn: (key: TEnum[keyof TEnum], vars?: Record<string, string | number>, language?: TLanguage) => string, enumName: string): <T extends string>(str: IsValidEnumTemplate<T, TEnum> extends true ? T : never, language?: TLanguage, ...otherVars: Record<string, string | number>[]) => string;

package/dist/src/template.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTemplateProcessor = createTemplateProcessor;
+/**
+ * Template function that processes {{EnumName.EnumKey}} patterns
+ */
+function createTemplateProcessor(enumObj, translateFn, enumName) {
+    return function t(str, language, ...otherVars) {
+        let varIndex = 0;
+        const pattern = new RegExp(`\\{\\{${enumName}\\.(\\w+)\\}\\}`, 'g');
+        // First replace enum patterns
+        let result = str.replace(pattern, (match, enumKey) => {
+            const enumValue = enumObj[enumKey];
+            if (!enumValue) {
+                return match; // Return original if enum key not found
+            }
+            const needsVars = enumValue
+                .toLowerCase()
+                .endsWith('template');
+            const vars = needsVars ? otherVars[varIndex++] ?? {} : {};
+            return translateFn(enumValue, vars, language);
+        });
+        // Then replace any remaining variables from all otherVars
+        const allVars = otherVars.reduce((acc, vars) => ({ ...acc, ...vars }), {});
+        result = result.replace(/\{(\w+)\}/g, (match, varName) => {
+            return allVars[varName] !== undefined ? String(allVars[varName]) : match;
+        });
+        return result;
+    };
+}

package/dist/src/timezone.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Class representing a validated timezone.
+ */
+export declare class Timezone {
+    private readonly _timezone;
+    constructor(timezone: string);
+    /**
+     * Gets the timezone value.
+     */
+    get value(): string;
+}

package/dist/src/timezone.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Timezone = void 0;
+const utils_1 = require("./utils");
+/**
+ * Class representing a validated timezone.
+ */
+class Timezone {
+    constructor(timezone) {
+        if (!(0, utils_1.isValidTimezone)(timezone)) {
+            throw new Error(`Invalid timezone: ${timezone}`);
+        }
+        this._timezone = timezone;
+    }
+    /**
+     * Gets the timezone value.
+     */
+    get value() {
+        return this._timezone;
+    }
+}
+exports.Timezone = Timezone;

package/dist/src/types.d.ts

@@ -0,0 +1,78 @@
+import { CurrencyCode } from './currency-code';
+import { Timezone } from './timezone';
+/**
+ * Standard language contexts
+ */
+export type LanguageContext = 'admin' | 'user' | 'system' | 'api';
+/**
+ * Default currency code
+ */
+export declare const DefaultCurrencyCode: string;
+/**
+ * Currency position type
+ */
+export type CurrencyPosition = 'prefix' | 'postfix' | 'infix';
+/**
+ * Custom language context type
+ */
+export type CustomLanguageContext<T extends string = LanguageContext> = T;
+/**
+ * Collection of localized strings for a specific language
+ */
+export type StringsCollection<TStringKey extends string> = Partial<Record<TStringKey, string>>;
+/**
+ * Mapping of languages to their respective string collections
+ */
+export type MasterStringsCollection<TStringKey extends string, TLanguage extends string> = Partial<Record<TLanguage, StringsCollection<TStringKey>>>;
+/**
+ * Mapping of language codes to their respective languages
+ */
+export type LanguageCodeCollection<TLanguage extends string> = Partial<Record<TLanguage, string>>;
+/**
+ * Mapping of enumeration values to their translations in multiple languages
+ */
+export type EnumTranslationMap<TEnum extends string | number, TLanguage extends string> = Partial<Record<TLanguage, Partial<Record<TEnum, string>>>>;
+/**
+ * I18n configuration interface
+ */
+export interface I18nConfig<TStringKey extends string, TLanguage extends string, TConstants extends Record<string, any> = Record<string, any>, TTranslationContext extends string = LanguageContext> {
+    stringNames: TStringKey[];
+    strings: MasterStringsCollection<TStringKey, TLanguage>;
+    defaultLanguage: TLanguage;
+    defaultTranslationContext: TTranslationContext;
+    defaultCurrencyCode: CurrencyCode;
+    languageCodes: LanguageCodeCollection<TLanguage>;
+    languages: TLanguage[];
+    constants?: TConstants;
+    enumName?: string;
+    enumObj?: Record<string, TStringKey>;
+    timezone: Timezone;
+    adminTimezone: Timezone;
+}
+/**
+ * I18n context interface
+ */
+export interface I18nContext<TLanguage extends string, TTranslationContext extends string = LanguageContext> {
+    language: TLanguage;
+    adminLanguage: TLanguage;
+    currencyCode: CurrencyCode;
+    currentContext: TTranslationContext;
+    timezone: Timezone;
+    adminTimezone: Timezone;
+}
+/**
+ * Generic translation type for any enumeration
+ */
+export type EnumTranslation<T extends string | number> = {
+    [K in T]: string;
+};
+/**
+ * Generic language translation type for any enumeration
+ */
+export type EnumLanguageTranslation<T extends string | number, TLanguage extends string = string> = Partial<{
+    [L in TLanguage]: EnumTranslation<T>;
+}>;
+/**
+ * Helper function to create typed translations for an enumeration
+ */
+export declare function createTranslations<T extends string | number, TLanguage extends string>(translations: EnumLanguageTranslation<T, TLanguage>): EnumLanguageTranslation<T, TLanguage>;

package/dist/src/types.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultCurrencyCode = void 0;
+exports.createTranslations = createTranslations;
+/**
+ * Default currency code
+ */
+exports.DefaultCurrencyCode = 'USD';
+/**
+ * Helper function to create typed translations for an enumeration
+ */
+function createTranslations(translations) {
+    return translations;
+}

package/dist/src/utils.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Replaces variables in a string with their corresponding values from vars or constants.
+ * @param str - The string containing variables to replace
+ * @param vars - An object mapping variable names to their replacement values
+ * @param constants - An object containing constant values for replacement
+ * @returns The string with variables replaced
+ */
+export declare function replaceVariables(str: string, vars?: Record<string, string | number>, constants?: any): string;
+/**
+ * Checks if a given key indicates a template string.
+ * @param key - The key to check
+ * @returns True if the key indicates a template, false otherwise
+ */
+export declare function isTemplate(key: string): boolean;
+/**
+ * Checks if a given timezone string is valid.
+ * @param timezone - The timezone string to validate
+ * @returns
+ */
+export declare function isValidTimezone(timezone: string): boolean;
+/**
+ * Converts parts to a single string key, joining with underscores.
+ * @param parts - The parts to join
+ * @returns The joined string key
+ */
+export declare function toStringKey<TStringKey extends string>(...parts: (string)[]): TStringKey;
+/**
+ * Converts an enum value to a string key by joining parts with underscores and appending the enum value.
+ * @param enumObj - The enum object
+ * @param value - The enum value
+ * @param parts - Additional parts to join
+ * @returns The constructed string key
+ */
+export declare function toStringKeyFromEnum<TStringKey extends string, TEnum extends string>(value: TEnum[keyof TEnum], ...parts: (string)[]): TStringKey;
+/**
+ * Builds a reason map from an enum object, mapping each enum value to a string key.
+ * @param enumObj - The enum object
+ * @param prefixes - Prefixes to prepend to each string key
+ * @returns The constructed reason map
+ */
+export declare function buildReasonMap<TStringKey extends string, TEnum extends Record<string, string>>(enumObj: TEnum, ...prefixes: string[]): Record<string, TStringKey>;

package/dist/src/utils.js

@@ -0,0 +1,85 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.replaceVariables = replaceVariables;
+exports.isTemplate = isTemplate;
+exports.isValidTimezone = isValidTimezone;
+exports.toStringKey = toStringKey;
+exports.toStringKeyFromEnum = toStringKeyFromEnum;
+exports.buildReasonMap = buildReasonMap;
+const moment_timezone_1 = __importDefault(require("moment-timezone"));
+/**
+ * Replaces variables in a string with their corresponding values from vars or constants.
+ * @param str - The string containing variables to replace
+ * @param vars - An object mapping variable names to their replacement values
+ * @param constants - An object containing constant values for replacement
+ * @returns The string with variables replaced
+ */
+function replaceVariables(str, vars, constants) {
+    const variables = str.match(/\{(.+?)\}/g);
+    if (!variables)
+        return str;
+    let result = str;
+    for (const variable of variables) {
+        const varName = variable.slice(1, -1);
+        let replacement = '';
+        if (vars && varName in vars) {
+            replacement = String(vars[varName]);
+        }
+        else if (constants && varName in constants) {
+            replacement = String(constants[varName]);
+        }
+        if (replacement) {
+            result = result.replace(variable, replacement);
+        }
+    }
+    return result;
+}
+/**
+ * Checks if a given key indicates a template string.
+ * @param key - The key to check
+ * @returns True if the key indicates a template, false otherwise
+ */
+function isTemplate(key) {
+    return key.trim().toLowerCase().endsWith('template');
+}
+/**
+ * Checks if a given timezone string is valid.
+ * @param timezone - The timezone string to validate
+ * @returns
+ */
+function isValidTimezone(timezone) {
+    return moment_timezone_1.default.tz.zone(timezone) !== null;
+}
+/**
+ * Converts parts to a single string key, joining with underscores.
+ * @param parts - The parts to join
+ * @returns The joined string key
+ */
+function toStringKey(...parts) {
+    return parts.join('_');
+}
+/**
+ * Converts an enum value to a string key by joining parts with underscores and appending the enum value.
+ * @param enumObj - The enum object
+ * @param value - The enum value
+ * @param parts - Additional parts to join
+ * @returns The constructed string key
+ */
+function toStringKeyFromEnum(value, ...parts) {
+    return parts.join('_') + '_' + String(value);
+}
+/**
+ * Builds a reason map from an enum object, mapping each enum value to a string key.
+ * @param enumObj - The enum object
+ * @param prefixes - Prefixes to prepend to each string key
+ * @returns The constructed reason map
+ */
+function buildReasonMap(enumObj, ...prefixes) {
+    return Object.values(enumObj).reduce((map, value) => {
+        map[value] = toStringKeyFromEnum(value, ...prefixes);
+        return map;
+    }, {});
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@digitaldefiance/i18n-lib",
-  "version": "1.0.22",
+  "version": "1.0.24",
   "description": "Generic i18n library with enum translation support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "yarn tsc",
-    "test": "yarn jest",
+    "test": "yarn jest --detectOpenHandles",
     "lint": "eslint src/**/*.ts tests/**/*.ts",
     "lint:fix": "eslint src/**/*.ts tests/**/*.ts --fix",
     "prettier:check": "prettier --check 'src/**/*.{ts,tsx}' 'tests/**/*.{ts,tsx}'",

package/dist/global-active-context.d.ts

@@ -1,22 +0,0 @@
-import { StringLanguage } from './enumerations/string-language';
-import { IActiveContext } from './interfaces/active-context';
-import { CurrencyCode } from './interfaces/currency-code';
-import { LanguageContext } from './shared-types';
-import { Timezone } from '@digitaldefiance/i18n-lib';
-export declare const GlobalActiveContext: IActiveContext;
-export declare function setUserLanguage(language: StringLanguage): void;
-export declare function setCurrencyCode(code: CurrencyCode): void;
-/**
- * Sets the admin language for console operations
- * @param language The language to set for admin operations
- */
-export declare function setAdminLanguage(language: StringLanguage): void;
-/**
- * Sets the language context for the current context
- * @param context The language context to set
- */
-export declare function setLanguageContext(context: LanguageContext): void;
-export declare function setSystemContext(): void;
-export declare function setApiContext(): void;
-export declare function setUserTimezone(tz: Timezone): void;
-export declare function setAdminTimezone(tz: Timezone): void;