@digitaldefiance/i18n-lib 3.7.5 → 3.8.1

package/src/core-plugin-factory.ts

@@ -0,0 +1,111 @@
+/**
+ * Factory for creating core plugin I18n engine instances
+ * This file breaks the circular dependency between core-i18n.ts and plugin-i18n-engine.ts
+ */
+
+import {
+  createCoreComponentRegistration,
+  createDefaultLanguages,
+} from './core-i18n';
+import { PluginI18nEngine } from './plugin-i18n-engine';
+import { RegistryConfig } from './registry-config';
+
+const DefaultInstanceKey = 'default';
+
+/**
+ * Create a pre-configured I18n engine with core components
+ * Returns engine with string type - use registry for language validation
+ */
+export function createCorePluginI18nEngine(
+  instanceKey: string = DefaultInstanceKey,
+  config?: Partial<RegistryConfig<string>>,
+): PluginI18nEngine<string> {
+  const languages = createDefaultLanguages();
+  const engine = PluginI18nEngine.createInstance<string>(
+    instanceKey,
+    languages,
+    config,
+  );
+  engine.registerComponent(createCoreComponentRegistration());
+  return engine;
+}
+
+// Note: Lazy initialization to avoid circular dependency issues
+// Tests should call resetCorePluginI18nEngine() after PluginI18nEngine.resetAll()
+let _corePluginI18nEngine: PluginI18nEngine<string> | undefined;
+
+export function getCorePluginI18nEngine(): PluginI18nEngine<string> {
+  // Lazy initialization on first access
+  if (!_corePluginI18nEngine) {
+    _corePluginI18nEngine = createCorePluginI18nEngine();
+    return _corePluginI18nEngine;
+  }
+
+  // Lazy re-initialization if instance was cleared
+  try {
+    PluginI18nEngine.getInstance<string>(DefaultInstanceKey);
+    return _corePluginI18nEngine;
+  } catch {
+    _corePluginI18nEngine = createCorePluginI18nEngine();
+    return _corePluginI18nEngine;
+  }
+}
+
+// Getter for direct reference - lazily initialized
+export const corePluginI18nEngine = new Proxy({} as PluginI18nEngine<string>, {
+  get(_target, prop) {
+    const engine = getCorePluginI18nEngine();
+    return engine[prop as keyof PluginI18nEngine<string>];
+  },
+});
+
+// Reset function for tests
+export function resetCorePluginI18nEngine(): void {
+  _corePluginI18nEngine = undefined;
+}
+
+/**
+ * Type alias for easier usage
+ */
+export type CorePluginI18nEngine = PluginI18nEngine<string>;
+
+/**
+ * Helper function to get core translation
+ * Uses the core engine instance to ensure core strings are available
+ */
+export function getCorePluginTranslation(
+  stringKey: string,
+  variables?: Record<string, string | number>,
+  language?: string,
+  instanceKey?: string,
+): string {
+  // Use string literal to avoid circular dependency
+  const coreComponentId = 'core';
+
+  // Use core engine if no instance key specified, otherwise use specified instance
+  const engine = instanceKey
+    ? PluginI18nEngine.getInstance<string>(instanceKey)
+    : getCorePluginI18nEngine();
+  return engine.translate(coreComponentId, stringKey, variables, language);
+}
+
+/**
+ * Helper function to safely get core translation with fallback
+ */
+export function safeCorePluginTranslation(
+  stringKey: string,
+  variables?: Record<string, string | number>,
+  language?: string,
+  instanceKey?: string,
+): string {
+  try {
+    return getCorePluginTranslation(
+      stringKey,
+      variables,
+      language,
+      instanceKey,
+    );
+  } catch {
+    return `[CoreStringKey.${stringKey}]`;
+  }
+}

package/src/core-string-key.ts

@@ -0,0 +1,59 @@
+/**
+ * Core system string keys
+ */
+export enum CoreStringKey {
+  // Common/General
+  Common_Yes = 'common_yes',
+  Common_No = 'common_no',
+  Common_Cancel = 'common_cancel',
+  Common_OK = 'common_ok',
+  Common_Save = 'common_save',
+  Common_Delete = 'common_delete',
+  Common_Edit = 'common_edit',
+  Common_Create = 'common_create',
+  Common_Update = 'common_update',
+  Common_Loading = 'common_loading',
+  Common_Error = 'common_error',
+  Common_Success = 'common_success',
+  Common_Warning = 'common_warning',
+  Common_Info = 'common_info',
+  Common_Disposed = 'common_disposed',
+  Common_Test = 'common_test',
+  // Error Messages
+  Error_InvalidInput = 'error_invalidInput',
+  Error_NetworkError = 'error_networkError',
+  Error_NotFound = 'error_notFound',
+  Error_AccessDenied = 'error_accessDenied',
+  Error_InternalServer = 'error_internalServer',
+  Error_ValidationFailed = 'error_validationFailed',
+  Error_RequiredField = 'error_requiredField',
+  Error_InvalidContext = 'error_invalidContext',
+  Error_InvalidContextTemplate = 'error_invalidContextTemplate',
+  Error_InvalidCurrencyCodeTemplate = 'error_invalidCurrencyCodeTemplate',
+
+  // Registry Errors (templates support variables)
+  Error_ComponentNotFoundTemplate = 'error_componentNotFoundTemplate',
+  Error_LanguageNotFoundTemplate = 'error_languageNotFoundTemplate',
+  Error_StringKeyNotFoundTemplate = 'error_stringKeyNotFoundTemplate',
+  Error_IncompleteRegistrationTemplate = 'error_incompleteRegistrationTemplate',
+  Error_DuplicateComponentTemplate = 'error_duplicateComponentTemplate',
+  Error_DuplicateLanguageTemplate = 'error_duplicateLanguageTemplate',
+  Error_ValidationFailedTemplate = 'error_validationFailedTemplate',
+  Error_MissingTranslationKeyTemplate = 'error_missingTranslationKeyTemplate',
+
+  // System Messages
+  System_Welcome = 'system_welcome',
+  System_Goodbye = 'system_goodbye',
+  System_PleaseWait = 'system_pleaseWait',
+  System_ProcessingRequest = 'system_processingRequest',
+  System_OperationComplete = 'system_operationComplete',
+  System_NoDataAvailable = 'system_noDataAvailable',
+
+  // DefaultStringKey
+  Error_InstanceAlreadyExistsTemplate = 'error_instanceAlreadyExistsTemplate',
+  Error_InstanceNotFoundTemplate = 'error_instanceNotFoundTemplate',
+  Error_MissingStringCollectionTemplate = 'error_missingStringCollectionTemplate',
+  Error_MissingTranslationTemplate = 'error_missingTranslationTemplate',
+  Error_DefaultLanguageNoCollectionTemplate = 'error_defaultLanguageNoCollectionTemplate',
+  Error_MissingTranslationKeyForTypeTemplate = 'error_missingTranslationKeyForTypeTemplate',
+}

package/src/create-translation-adapter.ts

@@ -0,0 +1,93 @@
+import { PluginI18nEngine } from './plugin-i18n-engine';
+import { TranslationEngine } from './translation-engine';
+
+/**
+ * Creates a TranslationEngine adapter from a PluginI18nEngine for a specific component.
+ * This allows PluginI18nEngine to be used where TranslationEngine interface is expected.
+ * 
+ * The adapter supports both calling conventions:
+ * - Full TranslationEngine interface: `translate(componentId, key, vars, lang)`
+ * - Simplified interface: `translate(key, vars, lang)` (componentId is bound)
+ *
+ * @param pluginEngine - The PluginI18nEngine instance to wrap
+ * @param componentId - The component ID to use for translations
+ * @returns A TranslationEngine that delegates to the PluginI18nEngine
+ *
+ * @example
+ * ```typescript
+ * const pluginEngine = getMyPluginI18nEngine();
+ * const adapter = createTranslationAdapter(pluginEngine, 'my-component');
+ *
+ * // Simplified interface (componentId is bound)
+ * const text1 = adapter.translate('key');
+ * const text2 = adapter.translate('key', { var: 'value' });
+ * const text3 = adapter.translate('key', { var: 'value' }, 'fr');
+ *
+ * // Full TranslationEngine interface
+ * const text4 = adapter.translate('other-component', 'key', { var: 'value' }, 'fr');
+ * ```
+ */
+export function createTranslationAdapter<
+  TStringKey extends string,
+  TLanguage extends string,
+>(
+  pluginEngine: PluginI18nEngine<TLanguage>,
+  componentId: string,
+): TranslationEngine<TStringKey> & {
+  translate(key: TStringKey, vars?: Record<string, string | number>, lang?: TLanguage): string;
+  safeTranslate(key: TStringKey, vars?: Record<string, string | number>, lang?: TLanguage): string;
+} {
+  const adapter: any = {
+    translate: (
+      keyOrComponentId: string | TStringKey,
+      varsOrKey?: TStringKey | Record<string, string | number>,
+      langOrVars?: TLanguage | Record<string, string | number>,
+      maybeLang?: TLanguage,
+    ): string => {
+      let actualKey: TStringKey;
+      let actualVars: Record<string, string | number> | undefined;
+      let actualLang: TLanguage | undefined;
+
+      if (arguments.length >= 4 || (typeof varsOrKey === 'string')) {
+        actualKey = varsOrKey as TStringKey;
+        actualVars = langOrVars as Record<string, string | number> | undefined;
+        actualLang = maybeLang;
+      } else {
+        actualKey = keyOrComponentId as TStringKey;
+        actualVars = varsOrKey as Record<string, string | number> | undefined;
+        actualLang = langOrVars as TLanguage | undefined;
+      }
+
+      try {
+        return pluginEngine.translate(componentId, actualKey, actualVars, actualLang);
+      } catch (error) {
+        return String(actualKey);
+      }
+    },
+
+    safeTranslate: (
+      keyOrComponentId: string | TStringKey,
+      varsOrKey?: TStringKey | Record<string, string | number>,
+      langOrVars?: TLanguage | Record<string, string | number>,
+      maybeLang?: TLanguage,
+    ): string => {
+      let actualKey: TStringKey;
+      let actualVars: Record<string, string | number> | undefined;
+      let actualLang: TLanguage | undefined;
+
+      if (arguments.length >= 4 || (typeof varsOrKey === 'string')) {
+        actualKey = varsOrKey as TStringKey;
+        actualVars = langOrVars as Record<string, string | number> | undefined;
+        actualLang = maybeLang;
+      } else {
+        actualKey = keyOrComponentId as TStringKey;
+        actualVars = varsOrKey as Record<string, string | number> | undefined;
+        actualLang = langOrVars as TLanguage | undefined;
+      }
+
+      return pluginEngine.safeTranslate(componentId, actualKey, actualVars, actualLang);
+    },
+  };
+
+  return adapter;
+}

package/src/enum-registry.ts

@@ -0,0 +1,152 @@
+import { EnumLanguageTranslation } from './types';
+
+/**
+ * Registry for managing translations of enum values across multiple languages.
+ *
+ * @template TStringKey Type of translation key used in error messages.
+ * @template TLanguage Type of supported language codes.
+ */
+export class EnumTranslationRegistry<
+  TStringKey extends string,
+  TLanguage extends string,
+> {
+  protected translations = new Map<any, EnumLanguageTranslation<any, TLanguage>>();
+  protected enumNames = new WeakMap<any, string>();
+  protected availableLanguages: Set<TLanguage>;
+  protected translateFn?: (key: TStringKey, vars?: Record<string, any>) => string;
+
+  /**
+   * Creates a new EnumTranslationRegistry.
+   *
+   * @param availableLanguages Array of supported language codes.
+   * @param translateFn Optional translation function for error templates.
+   */
+  constructor(
+    availableLanguages: TLanguage[],
+    translateFn?: (key: TStringKey, vars?: Record<string, any>) => string,
+  ) {
+    this.availableLanguages = new Set(availableLanguages);
+    this.translateFn = translateFn;
+  }
+
+  /**
+   * Registers an enum and its language-specific translations.
+   *
+   * @template TEnum Enum value type (string or number).
+   * @param enumObj The enum object to register.
+   * @param translations Mapping of language codes to value-to-string translations.
+   * @param enumName Human-readable name of the enum (used in errors).
+   * @throws {Error} If translations contain languages not in availableLanguages.
+   */
+  public register<TEnum extends string | number>(
+    enumObj: Record<string, TEnum>,
+    translations: EnumLanguageTranslation<TEnum, TLanguage>,
+    enumName: string,
+  ): void {
+    this.validateTranslations(translations, enumName);
+    this.translations.set(enumObj, translations);
+    this.enumNames.set(enumObj, enumName);
+  }
+
+  /**
+   * Translates a specific enum value into the target language.
+   *
+   * @template TEnum Enum value type.
+   * @param enumObj The enum object registered previously.
+   * @param value The enum value to translate.
+   * @param language The target language code.
+   * @returns The translated string.
+   * @throws {Error} If the enum or language or value is not found.
+   */
+  public translate<TEnum extends string | number>(
+    enumObj: Record<string, TEnum>,
+    value: TEnum,
+    language: TLanguage,
+  ): string {
+    const translations = this.translations.get(enumObj);
+    if (!translations) {
+      const message = this.translateFn
+        ? this.translateFn('Error_EnumNotFoundTemplate' as TStringKey, {
+            enumName: this.getEnumName(enumObj),
+          })
+        : `No translations found for enum: ${this.getEnumName(enumObj)}`;
+      throw new Error(message);
+    }
+
+    const langTranslations = translations[language];
+    if (!langTranslations) {
+      const message = this.translateFn
+        ? this.translateFn('Error_EnumLanguageNotFoundTemplate' as TStringKey, {
+            language,
+          })
+        : `No translations found for language: ${language}`;
+      throw new Error(message);
+    }
+
+    let result = langTranslations[value];
+    if (!result && typeof value === 'number') {
+      const stringKey = Object.keys(enumObj).find(
+        (key) => enumObj[key] === value,
+      );
+      if (stringKey) {
+        result = langTranslations[stringKey as TEnum];
+      }
+    }
+
+    if (!result) {
+      const message = this.translateFn
+        ? this.translateFn('Error_EnumValueNotFoundTemplate' as TStringKey, {
+            value: String(value),
+          })
+        : `No translation found for value: ${String(value)}`;
+      throw new Error(message);
+    }
+
+    return result;
+  }
+
+  /**
+   * Checks whether translations exist for the given enum object.
+   *
+   * @param enumObj The enum object to check.
+   * @returns True if registered, false otherwise.
+   */
+  public has(enumObj: any): boolean {
+    return this.translations.has(enumObj);
+  }
+
+  /**
+   * Internal: Retrieves the human-readable name of the enum.
+   *
+   * @param enumObj The enum object.
+   * @returns Registered enum name or 'UnknownEnum' if not set.
+   */
+  private getEnumName(enumObj: any): string {
+    return this.enumNames.get(enumObj) || 'UnknownEnum';
+  }
+
+  /**
+   * Internal: Validates that translation entries only use available languages.
+   *
+   * @template TEnum Enum value type.
+   * @param translations Mapping of language codes to translations.
+   * @param enumName Enum name for error reporting.
+   * @throws {Error} If a translation language is not available.
+   */
+  private validateTranslations<TEnum extends string | number>(
+    translations: EnumLanguageTranslation<TEnum, TLanguage>,
+    enumName: string,
+  ): void {
+    for (const language of Object.keys(translations) as TLanguage[]) {
+      if (!this.availableLanguages.has(language)) {
+        const message = this.translateFn
+          ? this.translateFn(
+              'Error_EnumLanguageNotAvailableTemplate' as TStringKey,
+              { language, enumName },
+            )
+          : `Language '${language}' in enum '${enumName}' is not available in this registry`;
+        throw new Error(message);
+      }
+    }
+  }
+}

package/src/errors/base.ts

@@ -0,0 +1,8 @@
+/**
+ * Base error exports that don't depend on core modules
+ * These can be imported without triggering core module initialization
+ */
+
+export * from './enhanced-error-base';
+export * from './handleable';
+export * from './simple-typed-error';

package/src/errors/context-error.ts

@@ -0,0 +1,122 @@
+import { ContextErrorType } from '../context-error-type';
+import { CoreI18nComponentId } from '../core-component-id';
+import { CoreStringKey } from '../core-string-key';
+import { EnhancedErrorHelper } from './enhanced-error-base';
+
+// Lazy reference to I18nEngine to avoid circular dependencies
+let engineGetter: (() => any) | undefined;
+
+/**
+ * Error class for context-related failures in the i18n system.
+ * Thrown when attempting to access or manipulate an invalid or non-existent context.
+ *
+ * **i18n Feature Support:**
+ * - ICU MessageFormat variable substitution
+ * - Nested message paths detection
+ * - Number formatting for context depths/positions
+ * - SelectOrdinal for context priority levels
+ *
+ * **Translation String Examples:**
+ * ```typescript
+ * // ICU plural
+ * "Context has {count, plural, one {# issue} other {# issues}}"
+ *
+ * // ICU select + nested
+ * "{severity, select, low {Minor context issue} high {Critical context error}}"
+ *
+ * // Number formatting
+ * "Context exceeded {limit, number, integer} maximum depth"
+ * ```
+ */
+export class ContextError extends Error {
+  /** The type of context error */
+  public override readonly type: ContextErrorType;
+  /** The context key that caused the error, if applicable */
+  public readonly contextKey?: string;
+  /** Additional context metadata */
+  public override readonly metadata?: Record<string, any>;
+
+  /**
+   * Creates a new ContextError instance.
+   * @param type - The type of context error
+   * @param contextKey - Optional context key that caused the error
+   * @param variables - Additional variables for ICU message formatting
+   * @param language - Optional language code
+   */
+  constructor(
+    type: ContextErrorType,
+    contextKey?: string,
+    variables?: Record<string, string | number>,
+    language?: string,
+  ) {
+    // Lazy initialization: get engine instance at runtime to avoid circular dependencies
+    let message: string;
+    try {
+      // Lazy load I18nEngine to break circular dependency
+      if (!engineGetter) {
+        // Dynamically import at runtime
+        const coreModule = eval('require')('../core');
+        engineGetter = () => coreModule.I18nEngine.getInstance('default');
+      }
+      const engine = engineGetter();
+      const allVars = { ...variables, contextKey: contextKey || '' };
+      message = contextKey
+        ? engine.safeTranslate(
+            CoreI18nComponentId,
+            CoreStringKey.Error_InvalidContextTemplate,
+            allVars,
+            language,
+          )
+        : engine.safeTranslate(
+            CoreI18nComponentId,
+            CoreStringKey.Error_InvalidContext,
+            allVars,
+            language,
+          );
+    } catch {
+      // Fallback if engine not available
+      message = contextKey
+        ? `Invalid context: ${contextKey}`
+        : 'Invalid context';
+    }
+    super(message);
+    this.name = 'ContextError';
+    this.type = type;
+    this.contextKey = contextKey;
+    this.metadata = variables;
+  }
+
+  /**
+   * Create context error with nested path information
+   * Demonstrates selectordinal for depth level
+   */
+  static withNestedPath(
+    type: ContextErrorType,
+    contextPath: string,
+    language = 'en-US',
+  ): ContextError {
+    const analysis = EnhancedErrorHelper.analyzeKeyPath(contextPath);
+    return new ContextError(
+      type,
+      contextPath,
+      {
+        depth: analysis.depth,
+        isNested: analysis.isNested ? 'true' : 'false',
+      },
+      language,
+    );
+  }
+
+  /**
+   * Create context error with count information
+   * Demonstrates plural formatting
+   */
+  static withCount(
+    type: ContextErrorType,
+    contextKey: string,
+    count: number,
+    language = 'en-US',
+  ): ContextError {
+    return new ContextError(type, contextKey, { count }, language);
+  }
+}