@digitaldefiance/i18n-lib 3.8.0 → 3.8.2

package/src/core/{index.d.ts → index.ts}

@@ -4,10 +4,13 @@
  * Note: Using regular exports for classes and type-only exports for interfaces
  * to minimize runtime circular dependencies while maintaining type availability.
  */
+
+// Export classes (runtime dependencies)
 export { ComponentStore } from './component-store';
 export { ContextManager } from './context-manager';
 export { EnumRegistry } from './enum-registry';
 export { I18nEngine } from './i18n-engine';
 export { LanguageRegistry } from './language-registry';
+
+// Export types only (no runtime dependency)
 export type { Context } from './context-manager';
-//# sourceMappingURL=index.d.ts.map

package/src/core/language-registry.ts

@@ -0,0 +1,345 @@
+/**
+ * Static language registry (no generics)
+ */
+
+import { I18nError } from '../errors/i18n-error';
+import { LanguageDefinition } from '../interfaces';
+
+/**
+ * Class representing a static registry for language definitions.
+ */
+export class LanguageRegistry {
+  private static languages = new Map<string, LanguageDefinition>();
+  private static defaultLanguageId: string | null = null;
+
+  /**
+   * Registers a new language definition.
+   * @param language - The language definition to register.
+   * @throws {I18nError} If the language ID or code is already registered.
+   */
+  static register(language: LanguageDefinition): void {
+    if (this.languages.has(language.id)) {
+      throw I18nError.duplicateLanguage(language.id);
+    }
+
+    const existing = this.getByCode(language.code);
+    if (existing) {
+      throw I18nError.duplicateLanguage(language.id);
+    }
+
+    this.languages.set(language.id, language);
+
+    if (language.isDefault || !this.defaultLanguageId) {
+      this.defaultLanguageId = language.id;
+    }
+  }
+
+  /**
+   * Checks if a language ID is registered.
+   * @param languageId - The language ID to check.
+   * @returns True if the language ID is registered, false otherwise.
+   */
+  static has(languageId: string): boolean {
+    return this.languages.has(languageId);
+  }
+
+  /**
+   * Retrieves a language definition by its ID.
+   * @param languageId - The language ID to retrieve.
+   * @returns The language definition.
+   * @throws {I18nError} If the language ID is not found.
+   */
+  static get(languageId: string): LanguageDefinition {
+    const lang = this.languages.get(languageId);
+    if (!lang) {
+      throw I18nError.languageNotFound(languageId);
+    }
+    return lang;
+  }
+
+  /**
+   * Retrieves all registered language definitions.
+   * @returns An array of all language definitions.
+   */
+  static getAll(): readonly LanguageDefinition[] {
+    return Array.from(this.languages.values());
+  }
+
+  /**
+   * Retrieves all registered language IDs.
+   * @returns An array of all language IDs.
+   */
+  static getIds(): readonly string[] {
+    return Array.from(this.languages.keys());
+  }
+
+  /**
+   * Retrieves all registered language codes.
+   * @returns An array of all language codes.
+   */
+  static getCodes(): readonly string[] {
+    return Array.from(this.languages.values()).map((l) => l.code);
+  }
+
+  /**
+   * Retrieves an array of objects mapping language codes to their labels.
+   * @returns An array of objects with code and label properties.
+   */
+  static getCodeLabelMap(): { code: string; label: string }[] {
+    return Array.from(this.languages.values()).map((l) => ({
+      code: l.code,
+      label: l.name,
+    }));
+  }
+
+  /**
+   * Retrieves the default language definition.
+   * @returns The default language definition or null if none is set.
+   */
+  static getDefault(): LanguageDefinition | null {
+    if (!this.defaultLanguageId) {
+      return null;
+    }
+    return this.get(this.defaultLanguageId);
+  }
+
+  /**
+   * Retrieves a language definition by its code.
+   * @param code - The language code to retrieve.
+   * @returns The language definition or undefined if not found.
+   */
+  static getByCode(code: string): LanguageDefinition | undefined {
+    return Array.from(this.languages.values()).find((l) => l.code === code);
+  }
+
+  /**
+   * Determines the best matching language code based on requested and user default codes.
+   * @param requestedCode - The requested language code.
+   * @param userDefaultCode - The user's default language code.
+   * @returns The best matching language code.
+   * @throws {I18nError} If no default language is configured.
+   */
+  static getMatchingCode(
+    requestedCode?: string,
+    userDefaultCode?: string,
+  ): string {
+    const trimmedRequested = requestedCode?.trim();
+    const trimmedUserDefault = userDefaultCode?.trim();
+
+    if (trimmedRequested && this.getByCode(trimmedRequested)) {
+      return trimmedRequested;
+    }
+    if (trimmedUserDefault && this.getByCode(trimmedUserDefault)) {
+      return trimmedUserDefault;
+    }
+    const defaultLang = this.getDefault();
+    if (!defaultLang) {
+      throw I18nError.invalidConfig('No default language configured');
+    }
+    return defaultLang.code;
+  }
+
+  /**
+   * Clears all registered languages and resets the default language.
+   */
+  static clear(): void {
+    this.languages.clear();
+    this.defaultLanguageId = null;
+  }
+
+  // V1 compatibility methods
+
+  /**
+   * Checks if a language ID is registered (V1 compatibility).
+   * @param languageId - The language ID to check.
+   * @returns True if the language ID is registered, false otherwise.
+   */
+  static hasLanguage(languageId: string): boolean {
+    return this.has(languageId);
+  }
+
+  /**
+   * Registers a new language definition (V1 compatibility).
+   * @param language - The language definition to register.
+   */
+  static registerLanguage(language: LanguageDefinition): void {
+    this.register(language);
+  }
+
+  /**
+   * Registers multiple language definitions (V1 compatibility).
+   * @param languages - An array of language definitions to register.
+   */
+  static registerLanguages(languages: readonly LanguageDefinition[]): void {
+    languages.forEach((lang) => this.register(lang));
+  }
+
+  /**
+   * Retrieves all registered language IDs (V1 compatibility).
+   * @returns An array of all language IDs.
+   */
+  static getLanguageIds(): readonly string[] {
+    return this.getIds();
+  }
+
+  /**
+   * Retrieves all registered language definitions (V1 compatibility).
+   * @returns An array of all language definitions.
+   */
+  static getAllLanguages(): readonly LanguageDefinition[] {
+    return this.getAll();
+  }
+
+  /**
+   * Retrieves a language definition by its code (V1 compatibility).
+   * @param code - The language code to retrieve.
+   * @returns The language definition or undefined if not found.
+   */
+  static getLanguageByCode(code: string): LanguageDefinition | undefined {
+    return this.getByCode(code);
+  }
+
+  /**
+   * Retrieves a language definition by its ID (V1 compatibility).
+   * @param languageId - The language ID to retrieve.
+   * @returns The language definition or undefined if not found.
+   */
+  static getLanguage(languageId: string): LanguageDefinition | undefined {
+    try {
+      return this.get(languageId);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Checks if a language code is registered.
+   * @param code - The language code to check.
+   * @returns True if the language code is registered, false otherwise.
+   */
+  static hasLanguageCode(code: string): boolean {
+    return this.getByCode(code) !== undefined;
+  }
+
+  /**
+   * Retrieves the default language ID.
+   * @returns The default language ID or null if none is set.
+   */
+  static getDefaultLanguageId(): string | null {
+    return this.defaultLanguageId;
+  }
+
+  /**
+   * Retrieves the count of registered languages.
+   * @returns The number of registered languages.
+   */
+  static getLanguageCount(): number {
+    return this.languages.size;
+  }
+
+  /**
+   * Retrieves the default language definition.
+   * @returns The default language definition or null if none is set.
+   */
+  static getDefaultLanguage(): LanguageDefinition | null {
+    return this.getDefault();
+  }
+
+  /**
+   * Sets the default language by its ID.
+   * @param languageId - The language ID to set as default.
+   * @throws {I18nError} If the language ID is not registered.
+   */
+  static setDefaultLanguage(languageId: string): void {
+    if (!this.has(languageId)) {
+      throw I18nError.languageNotFound(languageId);
+    }
+    this.defaultLanguageId = languageId;
+  }
+
+  /**
+   * Validates that all required languages are registered.
+   * @param requiredLanguages - An array of required language IDs.
+   * @returns An object containing validation results, missing languages, and errors.
+   */
+  static validateRequiredLanguages(requiredLanguages: readonly string[]): {
+    isValid: boolean;
+    missingLanguages: readonly string[];
+    errors: readonly string[];
+  } {
+    const missingLanguages: string[] = [];
+    const errors: string[] = [];
+
+    for (const languageId of requiredLanguages) {
+      if (!this.has(languageId)) {
+        missingLanguages.push(languageId);
+        errors.push(`Required language '${languageId}' is not registered`);
+      }
+    }
+
+    return {
+      isValid: missingLanguages.length === 0,
+      missingLanguages,
+      errors,
+    };
+  }
+
+  /**
+   * Retrieves a mapping of language IDs to their display names.
+   * @returns An object mapping language IDs to display names.
+   */
+  static getLanguageDisplayNames(): Record<string, string> {
+    const result: Record<string, string> = {};
+    for (const [languageId, language] of this.languages) {
+      result[languageId] = language.name;
+    }
+    return result;
+  }
+
+  /**
+   * Retrieves a mapping of language IDs to their codes.
+   * @returns An object mapping language IDs to language codes.
+   */
+  static getLanguageCodeMapping(): Record<string, string> {
+    const result: Record<string, string> = {};
+    for (const [languageId, language] of this.languages) {
+      result[languageId] = language.code;
+    }
+    return result;
+  }
+
+  /**
+   * Finds languages whose names include the given partial name (case-insensitive).
+   * @param partialName - The partial name to search for.
+   * @returns An array of matching language definitions.
+   */
+  static findLanguagesByName(
+    partialName: string,
+  ): readonly LanguageDefinition[] {
+    const searchTerm = partialName.toLowerCase();
+    return Array.from(this.languages.values()).filter((language) =>
+      language.name.toLowerCase().includes(searchTerm),
+    );
+  }
+
+  /**
+   * Retrieves all registered language codes.
+   * @returns An array of all language codes.
+   */
+  static getLanguageCodes(): readonly string[] {
+    return this.getCodes();
+  }
+
+  /**
+   * Determines the best matching language code based on requested and user default codes.
+   * @param requestedCode - The requested language code.
+   * @param userDefaultCode - The user's default language code.
+   * @returns The best matching language code.
+   */
+  static getMatchingLanguageCode(
+    requestedCode?: string,
+    userDefaultCode?: string,
+  ): string {
+    return this.getMatchingCode(requestedCode, userDefaultCode);
+  }
+}

package/src/{core-component-id.d.ts → core-component-id.ts}

@@ -2,5 +2,4 @@
  * Core component ID constant
  * Extracted to separate file to avoid circular dependencies
  */
-export declare const CoreI18nComponentId = "core";
-//# sourceMappingURL=core-component-id.d.ts.map
+export const CoreI18nComponentId = 'core';

package/src/core-i18n.ts

@@ -0,0 +1,270 @@
+/**
+ * Core I18n component with default languages and system strings
+ */
+
+import { ComponentDefinition } from './component-definition';
+import { ComponentRegistration } from './component-registration';
+import { CoreI18nComponentId } from './core-component-id';
+import { CoreStringKey } from './core-string-key';
+import { I18nEngine } from './core/i18n-engine';
+import { ComponentConfig, EngineConfig } from './interfaces';
+import { LanguageCodes } from './language-codes';
+import { LanguageDefinition } from './language-definition';
+import { createCompleteComponentStrings } from './strict-types';
+import { germanStrings } from './strings/de';
+import { BritishEnglishStrings } from './strings/en-GB';
+import { americanEnglishString } from './strings/en-US';
+import { spanishStrings } from './strings/es';
+import { frenchStrings } from './strings/fr';
+import { japaneseStrings } from './strings/ja';
+import { ukrainianStrings } from './strings/uk';
+import { mandarinStrings } from './strings/zh-CN';
+
+// Re-export for backward compatibility
+export { CoreI18nComponentId };
+
+/**
+ * Helper function to create multiple language definitions
+ */
+function createLanguageDefinitions(
+  languages: Array<{
+    id: string;
+    name: string;
+    code: string;
+    isDefault?: boolean;
+  }>,
+): LanguageDefinition[] {
+  return languages.map((lang) => ({
+    id: lang.id,
+    name: lang.name,
+    code: lang.code,
+    isDefault: lang.isDefault || false,
+  }));
+}
+
+/**
+ * Core language code type - union of supported language codes
+ * Provides compile-time type safety for core languages
+ * For custom languages, extend this type or use string
+ */
+export type CoreLanguageCode =
+  (typeof LanguageCodes)[keyof typeof LanguageCodes];
+
+/**
+ * Flexible language code type - use when you want runtime-only validation
+ * Alias for string to indicate it's a language code
+ */
+export type FlexibleLanguageCode = string;
+
+/**
+ * Create default language definitions
+ */
+export function createDefaultLanguages(): LanguageDefinition[] {
+  return createLanguageDefinitions([
+    {
+      id: LanguageCodes.EN_US,
+      name: 'English (US)',
+      code: 'en-US',
+      isDefault: true,
+    },
+    {
+      id: LanguageCodes.EN_GB,
+      name: 'English (UK)',
+      code: 'en-GB',
+    },
+    {
+      id: LanguageCodes.FR,
+      name: 'Français',
+      code: 'fr',
+    },
+    {
+      id: LanguageCodes.ES,
+      name: 'Español',
+      code: 'es',
+    },
+    {
+      id: LanguageCodes.DE,
+      name: 'Deutsch',
+      code: 'de',
+    },
+    {
+      id: LanguageCodes.ZH_CN,
+      name: '中文 (简体)',
+      code: 'zh-CN',
+    },
+    {
+      id: LanguageCodes.JA,
+      name: '日本語',
+      code: 'ja',
+    },
+    {
+      id: LanguageCodes.UK,
+      name: 'Українська',
+      code: 'uk',
+    },
+  ]);
+}
+
+/**
+ * Core component definition
+ */
+export const CoreComponentDefinition: ComponentDefinition<CoreStringKey> = {
+  id: CoreI18nComponentId,
+  name: 'Core I18n System',
+  stringKeys: Object.values(CoreStringKey),
+};
+
+/**
+ * Core component strings for all default languages
+ */
+export function createCoreComponentStrings() {
+  return createCompleteComponentStrings<CoreStringKey, string>({
+    [LanguageCodes.EN_US]: americanEnglishString,
+    [LanguageCodes.EN_GB]: BritishEnglishStrings,
+    [LanguageCodes.FR]: frenchStrings,
+    [LanguageCodes.ES]: spanishStrings,
+    [LanguageCodes.DE]: germanStrings,
+    [LanguageCodes.ZH_CN]: mandarinStrings,
+    [LanguageCodes.JA]: japaneseStrings,
+    [LanguageCodes.UK]: ukrainianStrings,
+  });
+}
+
+/**
+ * Create core component registration (for PluginI18nEngine)
+ */
+export function createCoreComponentRegistration(): ComponentRegistration<
+  CoreStringKey,
+  string
+> {
+  return {
+    component: CoreComponentDefinition,
+    strings: createCoreComponentStrings(),
+  };
+}
+
+/**
+ * Create core component config (for I18nEngine)
+ */
+export function createCoreComponentConfig(): ComponentConfig {
+  return {
+    id: CoreI18nComponentId,
+    strings: createCoreComponentStrings(),
+    aliases: ['CoreStringKey'],
+  };
+}
+
+/**
+ * Get core language codes as array (for Mongoose enums, etc.)
+ */
+export function getCoreLanguageCodes(): string[] {
+  return Object.values(LanguageCodes);
+}
+
+/**
+ * Get core language definitions
+ */
+export function getCoreLanguageDefinitions(): LanguageDefinition[] {
+  return createDefaultLanguages();
+}
+
+// 1.x definitions moved to core-plugin-factory.ts to break circular dependency
+// Import these from './core-plugin-factory' or from the main index
+
+// 2.x definitions
+//------------------------------
+
+/**
+ * Create Core i18n engine instance
+ * Uses i18n 2.0 pattern with runtime validation
+ * IMPORTANT: Uses 'default' as instance key so TypedHandleableError can find it
+ */
+function createInstance(config?: EngineConfig): I18nEngine {
+  const engine = I18nEngine.registerIfNotExists(
+    'default',
+    createDefaultLanguages(),
+    config,
+  );
+
+  // Register core component if not already registered
+  const coreReg = createCoreComponentRegistration();
+  engine.registerIfNotExists({
+    id: coreReg.component.id,
+    strings: coreReg.strings as Record<string, Record<string, string>>,
+  });
+
+  return engine;
+}
+
+/**
+ * Lazy initialization with Proxy (like core-i18n.ts pattern)
+ */
+let _coreEngine: I18nEngine | undefined;
+
+export function getCoreI18nEngine(): I18nEngine {
+  // Lazy initialization on first access
+  if (!_coreEngine) {
+    // Check if instance exists before creating
+    if (I18nEngine.hasInstance('default')) {
+      _coreEngine = I18nEngine.getInstance('default');
+    } else {
+      _coreEngine = createInstance();
+    }
+    return _coreEngine;
+  }
+
+  // Lazy re-initialization if instance was cleared
+  if (I18nEngine.hasInstance('default')) {
+    return _coreEngine;
+  } else {
+    _coreEngine = createInstance();
+    return _coreEngine;
+  }
+}
+
+/**
+ * Proxy for backward compatibility
+ */
+export const coreI18nEngine = new Proxy({} as I18nEngine, {
+  get(target, prop) {
+    return getCoreI18nEngine()[prop as keyof I18nEngine];
+  },
+});
+
+/**
+ * Reset function for tests
+ */
+export function resetCoreI18nEngine(): void {
+  _coreEngine = undefined;
+}
+
+/**
+ * Helper to translate Core strings
+ */
+export function getCoreTranslation(
+  stringKey: CoreStringKey,
+  variables?: Record<string, string | number>,
+  language?: string,
+): string {
+  return getCoreI18nEngine().translate(
+    CoreI18nComponentId,
+    stringKey,
+    variables,
+    language,
+  );
+}
+
+/**
+ * Safe translation with fallback
+ */
+export function safeCoreTranslation(
+  stringKey: CoreStringKey,
+  variables?: Record<string, string | number>,
+  language?: string,
+): string {
+  try {
+    return getCoreTranslation(stringKey, variables, language);
+  } catch {
+    return `[${stringKey}]`;
+  }
+}