@digitaldefiance/i18n-lib 1.3.11 → 1.3.13

package/dist/handleable.js

@@ -1,56 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.HandleableError = void 0;
-class HandleableError extends Error {
-    constructor(source, options) {
-        super(source.message);
-        this.name = this.constructor.name;
-        this.cause = options?.cause ?? source;
-        this.statusCode = options?.statusCode ?? 500;
-        this._handled = options?.handled ?? false;
-        this.sourceData = options?.sourceData;
-        // Capture stack trace - prioritize source stack, then capture new one
-        if (source.stack) {
-            this.stack = source.stack;
-        }
-        else if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, this.constructor);
-        }
-        else {
-            this.stack = new Error().stack;
-        }
-    }
-    get handled() {
-        return this._handled;
-    }
-    set handled(value) {
-        this._handled = value;
-    }
-    serializeValue(value) {
-        if (value && typeof value === 'object' && 'toJSON' in value && typeof value.toJSON === 'function') {
-            return value.toJSON();
-        }
-        if (value instanceof Error) {
-            return value.message;
-        }
-        if (Array.isArray(value)) {
-            return value.map(item => this.serializeValue(item));
-        }
-        if (value && typeof value === 'object') {
-            return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, this.serializeValue(v)]));
-        }
-        return value;
-    }
-    toJSON() {
-        return {
-            name: this.name,
-            message: this.message,
-            statusCode: this.statusCode,
-            handled: this.handled,
-            stack: this.stack,
-            cause: this.serializeValue(this.cause),
-            ...(this.sourceData ? { sourceData: this.serializeValue(this.sourceData) } : {}),
-        };
-    }
-}
-exports.HandleableError = HandleableError;

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

@@ -1,22 +0,0 @@
-import { IActiveContext } from './active-context';
-import { CurrencyCode } from './currency-code';
-import { Timezone } from './timezone';
-import { LanguageContextSpace } from './types';
-export interface IGlobalActiveContext<TLanguage extends string, TActiveContext extends IActiveContext<TLanguage>> {
-    context: TActiveContext;
-    userLanguage: TLanguage;
-    currencyCode: CurrencyCode;
-    adminLanguage: TLanguage;
-    languageContextSpace: LanguageContextSpace;
-    userTimezone: Timezone;
-    adminTimezone: Timezone;
-    createContext(defaultLanguage: TLanguage, defaultAdminLanguage?: TLanguage, key?: string): TActiveContext;
-    getContext(key?: string): TActiveContext;
-    setUserLanguage(language: TLanguage, key?: string): void;
-    setCurrencyCode(code: CurrencyCode, key?: string): void;
-    setAdminLanguage(language: TLanguage, key?: string): void;
-    setLanguageContextSpace(context: LanguageContextSpace, key?: string): void;
-    getLanguageContextSpace(key?: string): LanguageContextSpace;
-    setUserTimezone(tz: Timezone, key?: string): void;
-    setAdminTimezone(tz: Timezone, key?: string): void;
-}

package/dist/i-global-active-context.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/i-handleable-error-options.d.ts

@@ -1,6 +0,0 @@
-export interface HandleableErrorOptions {
-    cause?: Error;
-    handled?: boolean;
-    statusCode?: number;
-    sourceData?: unknown;
-}

package/dist/i-handleable-error-options.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/i-handleable.d.ts

@@ -1,5 +0,0 @@
-export interface IHandleable {
-    toJSON(): Record<string, unknown>;
-    get handled(): boolean;
-    set handled(value: boolean);
-}

package/dist/i-handleable.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/i18n-config.d.ts

@@ -1,20 +0,0 @@
-import { CurrencyCode } from './currency-code';
-import { Timezone } from './timezone';
-import { LanguageCodeCollection, LanguageContextSpace, MasterStringsCollection } from './types';
-/**
- * I18n configuration interface
- */
-export interface I18nConfig<TStringKey extends string, TLanguage extends string, TConstants extends Record<string, any> = Record<string, any>> {
-    stringNames: TStringKey[];
-    strings: MasterStringsCollection<TStringKey, TLanguage>;
-    defaultLanguage: TLanguage;
-    defaultTranslationContext: LanguageContextSpace;
-    defaultCurrencyCode: CurrencyCode;
-    languageCodes: LanguageCodeCollection<TLanguage>;
-    languages: TLanguage[];
-    constants?: TConstants;
-    enumName?: string;
-    enumObj?: Record<string, TStringKey>;
-    timezone: Timezone;
-    adminTimezone: Timezone;
-}

package/dist/i18n-config.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/i18n-context.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/i18n-engine.d.ts

@@ -1,178 +0,0 @@
-import { EnumTranslationRegistry } from './enum-registry';
-import { I18nConfig } from './i18n-config';
-import { I18nContext } from './i18n-context';
-import { EnumLanguageTranslation } from './types';
-/**
- * Internationalization engine class
- */
-export declare class I18nEngine<TStringKey extends string, TLanguage extends string, TConstants extends Record<string, any> = Record<string, any>, TContext extends I18nContext<TLanguage> = I18nContext<TLanguage>> {
-    /**
-     * Registry for enum translations
-     */
-    protected _enumRegistry: EnumTranslationRegistry<TStringKey, TLanguage>;
-    /**
-     * Configuration for the i18n engine
-     */
-    readonly config: I18nConfig<TStringKey, TLanguage, TConstants>;
-    /**
-     * Static instances for semi-singleton pattern
-     */
-    private static _instances;
-    /**
-     * Default instance key (first created instance)
-     */
-    private static _defaultKey;
-    /**
-     * Default instance key if none is provided
-     */
-    protected static readonly DefaultInstanceKey = "default";
-    /**
-     * Global context for translations (used if no context is provided) for this instance
-     */
-    private _context;
-    /**
-     * Default template processor instance
-     */
-    readonly t: (str: string, language?: TLanguage, ...otherVars: Record<string, string | number>[]) => string;
-    /**
-     * 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: I18nConfig<TStringKey, TLanguage, TConstants>, key?: string, newContext?: () => TContext);
-    /**
-     * 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<T extends I18nEngine<any, any, any, any>>(key?: string): T;
-    /**
-     * 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: string, vars?: Record<string, string | number>, instanceKey?: string, language?: string, fallbackLanguage?: string): string;
-    /**
-     * 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: string, vars?: Record<string, string | number>, instanceKey?: string): never;
-    /**
-     * Gets the global context for translations
-     * @returns The global context object
-     */
-    get context(): TContext;
-    /**
-     * Sets the global context for translations (used if no context is provided) for this instance
-     * @param context The context to set
-     */
-    set context(context: Partial<TContext>);
-    /**
-     * Gets the enum translation registry for this engine instance
-     * @returns The enum translation registry
-     */
-    get enumRegistry(): EnumTranslationRegistry<TStringKey, TLanguage>;
-    /**
-     * 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: TStringKey, vars?: Record<string, string | number>, language?: TLanguage, fallbackLanguage?: TLanguage): string;
-    /**
-     * 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<TEnum extends string | number>(enumObj: Record<string, TEnum>, value: TEnum, language: TLanguage): string;
-    /**
-     * 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<TEnum extends string | number>(enumObj: Record<string, TEnum> | Record<string | number, string | number>, translations: EnumLanguageTranslation<TEnum, TLanguage>, enumName: string): void;
-    /**
-     * 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: TStringKey, vars?: Record<string, string | number>, language?: TLanguage): string;
-    /**
-     * 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
-     */
-    private getString;
-    /**
-     * Gets the language code for the specified language.
-     * @param language The language to get the code for
-     * @returns The language code
-     */
-    getLanguageCode(language: TLanguage): string;
-    /**
-     * 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: string): TLanguage | undefined;
-    /**
-     * Gets all language codes.
-     * @returns A record of all language codes
-     */
-    getAllLanguageCodes(): Record<TLanguage, string>;
-    /**
-     * Gets all available languages.
-     * @returns An array of all available languages
-     */
-    getAvailableLanguages(): TLanguage[];
-    /**
-     * Checks if a language is available.
-     * @param language The language to check
-     * @returns True if the language is available, false otherwise
-     */
-    isLanguageAvailable(language: string): language is TLanguage;
-    /**
-     * Clears all instances (for testing purposes)
-     * @internal
-     */
-    static clearInstances(): void;
-    /**
-     * Removes a specific instance by key
-     * @param key The key of the instance to remove
-     * @internal
-     */
-    static removeInstance(key?: string): void;
-    /**
-     * Static error message templates for validation
-     */
-    private static readonly ErrorTemplates;
-    /**
-     * Validates the configuration to ensure all languages have string collections
-     * and all string keys are provided for each language
-     * @param config The configuration to validate
-     * @throws Error if validation fails
-     */
-    private validateConfig;
-    /**
-     * Gets validation error message, trying translation first, falling back to template
-     */
-    private getValidationError;
-}

package/dist/i18n-engine.js

@@ -1,338 +0,0 @@
-"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.validateConfig(config);
-        this.config = config;
-        this._enumRegistry = new enum_registry_1.EnumTranslationRegistry(Object.keys(config.strings), (key, vars) => this.safeTranslate(key, vars));
-        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 };
-    }
-    /**
-     * Gets the enum translation registry for this engine instance
-     * @returns The enum translation registry
-     */
-    get enumRegistry() {
-        return this._enumRegistry;
-    }
-    /**
-     * 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);
-            let result = (0, utils_1.isTemplate)(key)
-                ? (0, utils_1.replaceVariables)(stringValue, vars, this.config.constants)
-                : stringValue;
-            // Ensure result is always a string
-            if (typeof result !== 'string') {
-                result = String(result);
-            }
-            return result;
-        }
-        catch {
-            if (lang !== fallback) {
-                try {
-                    const stringValue = this.getString(fallback, key);
-                    let result = (0, utils_1.isTemplate)(key)
-                        ? (0, utils_1.replaceVariables)(stringValue, vars, this.config.constants)
-                        : stringValue;
-                    // Ensure result is always a string
-                    if (typeof result !== 'string') {
-                        result = String(result);
-                    }
-                    return result;
-                }
-                catch {
-                    return String(key);
-                }
-            }
-            return String(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 String(key);
-            const stringValue = strings[key];
-            let result = (0, utils_1.isTemplate)(key)
-                ? (0, utils_1.replaceVariables)(stringValue, vars, this.config.constants)
-                : stringValue;
-            // Ensure result is always a string
-            if (typeof result !== 'string') {
-                result = String(result);
-            }
-            return result;
-        }
-        catch {
-            return String(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;
-        }
-    }
-    /**
-     * Validates the configuration to ensure all languages have string collections
-     * and all string keys are provided for each language
-     * @param config The configuration to validate
-     * @throws Error if validation fails
-     */
-    validateConfig(config) {
-        // Check that default language exists
-        if (!config.strings[config.defaultLanguage]) {
-            throw new Error(this.getValidationError('Error_DefaultLanguageNoCollectionTemplate', { language: config.defaultLanguage }, config));
-        }
-        // Check that all string keys are provided for each language that has strings
-        for (const language of Object.keys(config.strings)) {
-            const strings = config.strings[language];
-            for (const stringKey of config.stringNames) {
-                if (!strings[stringKey]) {
-                    throw new Error(this.getValidationError('Error_MissingTranslationTemplate', { key: stringKey, language }, config));
-                }
-            }
-        }
-    }
-    /**
-     * Gets validation error message, trying translation first, falling back to template
-     */
-    getValidationError(key, vars, config) {
-        try {
-            const strings = config.strings[config.defaultLanguage];
-            if (strings?.[key]) {
-                return (0, utils_1.replaceVariables)(strings[key], vars, config.constants);
-            }
-        }
-        catch { }
-        // Fallback to static templates
-        const template = key.includes('MissingStringCollection')
-            ? I18nEngine.ErrorTemplates.MissingStringCollection
-            : key.includes('MissingTranslation')
-                ? I18nEngine.ErrorTemplates.MissingTranslation
-                : I18nEngine.ErrorTemplates.DefaultLanguageNoCollection;
-        return (0, utils_1.replaceVariables)(template, vars);
-    }
-}
-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';
-/**
- * Static error message templates for validation
- */
-I18nEngine.ErrorTemplates = {
-    MissingStringCollection: 'Missing string collection for language: {language}',
-    MissingTranslation: "Missing translation for key '{key}' in language '{language}'",
-    DefaultLanguageNoCollection: "Default language '{language}' has no string collection",
-};