@hua-labs/i18n-core 1.0.0

package/src/core/lazy-loader.ts

@@ -0,0 +1,255 @@
+import { TranslationNamespace } from '../types';
+import { i18nResourceManager } from './i18n-resource';
+
+/**
+ * 네임스페이스별 지연 로딩 전략
+ * 대규모 앱에서 번역 단위 최적화를 위한 loadOnDemand 함수
+ */
+export class LazyLoader {
+  private static instance: LazyLoader;
+  private loadingQueue = new Map<string, Promise<TranslationNamespace>>();
+  private preloadCache = new Set<string>();
+  private loadHistory = new Map<string, number>();
+
+  private constructor() {}
+
+  static getInstance(): LazyLoader {
+    if (!LazyLoader.instance) {
+      LazyLoader.instance = new LazyLoader();
+    }
+    return LazyLoader.instance;
+  }
+
+  /**
+   * 필요할 때 네임스페이스 로딩
+   */
+  async loadOnDemand(
+    language: string,
+    namespace: string,
+    loader: (lang: string, ns: string) => Promise<TranslationNamespace>
+  ): Promise<TranslationNamespace> {
+    const cacheKey = `${language}:${namespace}`;
+    
+    // 이미 로딩 중이면 기존 Promise 반환
+    if (this.loadingQueue.has(cacheKey)) {
+      return this.loadingQueue.get(cacheKey)!;
+    }
+
+    // 캐시에 있으면 반환
+    const cached = i18nResourceManager.getCachedTranslationsSync(language, namespace);
+    if (cached) {
+      this.updateLoadHistory(cacheKey);
+      return cached;
+    }
+
+    // 새로 로딩
+    const loadPromise = this.performLoad(language, namespace, loader);
+    this.loadingQueue.set(cacheKey, loadPromise);
+
+    try {
+      const result = await loadPromise;
+      this.updateLoadHistory(cacheKey);
+      return result;
+    } finally {
+      this.loadingQueue.delete(cacheKey);
+    }
+  }
+
+  /**
+   * 실제 로딩 수행
+   */
+  private async performLoad(
+    language: string,
+    namespace: string,
+    loader: (lang: string, ns: string) => Promise<TranslationNamespace>
+  ): Promise<TranslationNamespace> {
+    const result = await i18nResourceManager.getCachedTranslations(language, namespace, loader);
+    return result;
+  }
+
+  /**
+   * 로딩 히스토리 업데이트
+   */
+  private updateLoadHistory(cacheKey: string): void {
+    this.loadHistory.set(cacheKey, Date.now());
+  }
+
+  /**
+   * 네임스페이스 사전 로딩
+   */
+  async preloadNamespace(
+    language: string,
+    namespace: string,
+    loader: (lang: string, ns: string) => Promise<TranslationNamespace>
+  ): Promise<void> {
+    const cacheKey = `${language}:${namespace}`;
+    
+    if (this.preloadCache.has(cacheKey)) {
+      return; // 이미 사전 로딩됨
+    }
+
+    try {
+      await this.loadOnDemand(language, namespace, loader);
+      this.preloadCache.add(cacheKey);
+    } catch (error) {
+      // Silent fail for preloading
+    }
+  }
+
+  /**
+   * 여러 네임스페이스 동시 사전 로딩
+   */
+  async preloadMultipleNamespaces(
+    language: string,
+    namespaces: string[],
+    loader: (lang: string, ns: string) => Promise<TranslationNamespace>
+  ): Promise<void> {
+    const promises = namespaces.map(namespace => 
+      this.preloadNamespace(language, namespace, loader)
+    );
+    
+    await Promise.allSettled(promises);
+  }
+
+  /**
+   * 사용 패턴 기반 자동 사전 로딩
+   */
+  async autoPreload(
+    language: string,
+    currentNamespace: string,
+    loader: (lang: string, ns: string) => Promise<TranslationNamespace>
+  ): Promise<void> {
+    // 현재 네임스페이스와 관련된 네임스페이스들 자동 사전 로딩
+    const relatedNamespaces = this.getRelatedNamespaces(currentNamespace);
+    
+    for (const namespace of relatedNamespaces) {
+      await this.preloadNamespace(language, namespace, loader);
+    }
+  }
+
+  /**
+   * 관련 네임스페이스 추정
+   */
+  private getRelatedNamespaces(currentNamespace: string): string[] {
+    // 실제 구현에서는 사용 패턴 분석을 통해 관련 네임스페이스 추정
+    const namespacePatterns: Record<string, string[]> = {
+      'auth': ['common', 'validation', 'errors'],
+      'dashboard': ['common', 'navigation', 'stats'],
+      'profile': ['common', 'auth', 'validation'],
+      'settings': ['common', 'navigation', 'forms'],
+      'common': ['errors', 'validation']
+    };
+
+    return namespacePatterns[currentNamespace] || [];
+  }
+
+  /**
+   * 로딩 우선순위 설정
+   */
+  setLoadPriority(namespaces: string[]): void {
+    // 우선순위가 높은 네임스페이스들을 먼저 로딩
+  }
+
+  /**
+   * 로딩 통계 가져오기
+   */
+  getLoadStats() {
+    return {
+      loadingQueueSize: this.loadingQueue.size,
+      preloadedCount: this.preloadCache.size,
+      loadHistorySize: this.loadHistory.size
+    };
+  }
+
+  /**
+   * 메모리 최적화
+   */
+  optimizeMemory(): void {
+    // 오래된 로딩 히스토리 정리
+    const now = Date.now();
+    const oneHour = 60 * 60 * 1000;
+    
+    for (const [key, timestamp] of this.loadHistory.entries()) {
+      if (now - timestamp > oneHour) {
+        this.loadHistory.delete(key);
+      }
+    }
+  }
+
+  /**
+   * 네임스페이스 사용 빈도 분석
+   */
+  analyzeUsagePatterns(): Record<string, number> {
+    const usage: Record<string, number> = {};
+    
+    for (const [key, timestamp] of this.loadHistory.entries()) {
+      const namespace = key.split(':')[1];
+      usage[namespace] = (usage[namespace] || 0) + 1;
+    }
+    
+    return usage;
+  }
+
+  /**
+   * 캐시 무효화
+   */
+  invalidateCache(language?: string, namespace?: string): void {
+    i18nResourceManager.invalidateCache(language, namespace);
+    
+    if (language && namespace) {
+      const cacheKey = `${language}:${namespace}`;
+      this.preloadCache.delete(cacheKey);
+      this.loadHistory.delete(cacheKey);
+    } else if (language) {
+      // 특정 언어의 모든 캐시 무효화
+      for (const key of this.preloadCache) {
+        if (key.startsWith(`${language}:`)) {
+          this.preloadCache.delete(key);
+          this.loadHistory.delete(key);
+        }
+      }
+    } else {
+      // 전체 캐시 무효화
+      this.preloadCache.clear();
+      this.loadHistory.clear();
+    }
+  }
+}
+
+/**
+ * 전역 지연 로더 인스턴스
+ */
+export const lazyLoader = LazyLoader.getInstance();
+
+/**
+ * 편의 함수: 필요할 때 로딩
+ */
+export const loadOnDemand = (
+  language: string,
+  namespace: string,
+  loader: (lang: string, ns: string) => Promise<TranslationNamespace>
+) => {
+  return lazyLoader.loadOnDemand(language, namespace, loader);
+};
+
+/**
+ * 편의 함수: 사전 로딩
+ */
+export const preloadNamespace = (
+  language: string,
+  namespace: string,
+  loader: (lang: string, ns: string) => Promise<TranslationNamespace>
+) => {
+  return lazyLoader.preloadNamespace(language, namespace, loader);
+};
+
+/**
+ * 편의 함수: 자동 사전 로딩
+ */
+export const autoPreload = (
+  language: string,
+  currentNamespace: string,
+  loader: (lang: string, ns: string) => Promise<TranslationNamespace>
+) => {
+  return lazyLoader.autoPreload(language, currentNamespace, loader);
+}; 

package/src/core/translator-factory.ts

@@ -0,0 +1,137 @@
+import { Translator } from './translator';
+import { I18nConfig } from '../types';
+
+/**
+ * Translator 인스턴스를 관리하는 Factory 클래스
+ * - Config 변경 감지
+ * - 테스트 환경 격리
+ * - 메모리 관리
+ */
+export class TranslatorFactory {
+  private static instances = new Map<string, Translator>();
+  private static configCache = new Map<string, I18nConfig>();
+  private static readonly MAX_INSTANCES = 10; // 최대 인스턴스 수 제한
+
+  /**
+   * Config를 기반으로 고유 키 생성
+   */
+  private static generateConfigKey(config: I18nConfig): string {
+    // Config의 핵심 속성들을 기반으로 키 생성
+    const keyParts = [
+      config.defaultLanguage,
+      config.fallbackLanguage || 'en',
+      config.namespaces?.join(',') || 'common',
+      config.debug ? 'debug' : 'prod',
+    ];
+    return keyParts.join('|');
+  }
+
+  /**
+   * Config가 변경되었는지 확인
+   */
+  private static isConfigChanged(configKey: string, newConfig: I18nConfig): boolean {
+    const cachedConfig = this.configCache.get(configKey);
+    if (!cachedConfig) return true;
+
+    // 핵심 속성들만 비교
+    return (
+      cachedConfig.defaultLanguage !== newConfig.defaultLanguage ||
+      cachedConfig.fallbackLanguage !== newConfig.fallbackLanguage ||
+      JSON.stringify(cachedConfig.namespaces) !== JSON.stringify(newConfig.namespaces) ||
+      cachedConfig.debug !== newConfig.debug
+    );
+  }
+
+  /**
+   * Translator 인스턴스 생성 또는 반환
+   */
+  static create(config: I18nConfig): Translator {
+    const configKey = this.generateConfigKey(config);
+    
+    // Config가 변경되었거나 인스턴스가 없으면 새로 생성
+    if (!this.instances.has(configKey) || this.isConfigChanged(configKey, config)) {
+      // 최대 인스턴스 수 초과 시 오래된 인스턴스 제거 (LRU 방식)
+      if (this.instances.size >= this.MAX_INSTANCES && !this.instances.has(configKey)) {
+        // 가장 오래된 인스턴스 제거 (Map은 삽입 순서 유지)
+        const oldestKey = this.instances.keys().next().value;
+        if (oldestKey) {
+          const oldInstance = this.instances.get(oldestKey);
+          if (oldInstance) {
+            oldInstance.clearCache();
+          }
+          this.instances.delete(oldestKey);
+          this.configCache.delete(oldestKey);
+        }
+      }
+
+      // 기존 인스턴스 정리
+      if (this.instances.has(configKey)) {
+        const oldInstance = this.instances.get(configKey)!;
+        oldInstance.clearCache();
+      }
+      
+      // 새 인스턴스 생성
+      const newInstance = new Translator(config);
+      this.instances.set(configKey, newInstance);
+      this.configCache.set(configKey, { ...config });
+    }
+    
+    return this.instances.get(configKey)!;
+  }
+
+  /**
+   * 특정 Config 키의 Translator 인스턴스 반환
+   */
+  static get(config: I18nConfig): Translator | null {
+    const configKey = this.generateConfigKey(config);
+    return this.instances.get(configKey) || null;
+  }
+
+  /**
+   * 모든 Translator 인스턴스 정리 (테스트용)
+   */
+  static clear(): void {
+    // 모든 인스턴스의 캐시 정리
+    for (const instance of this.instances.values()) {
+      instance.clearCache();
+    }
+    
+    this.instances.clear();
+    this.configCache.clear();
+  }
+
+  /**
+   * 특정 Config 키의 인스턴스만 정리
+   */
+  static clearConfig(config: I18nConfig): void {
+    const configKey = this.generateConfigKey(config);
+    const instance = this.instances.get(configKey);
+    if (instance) {
+      instance.clearCache();
+      this.instances.delete(configKey);
+      this.configCache.delete(configKey);
+    }
+  }
+
+  /**
+   * 현재 관리 중인 인스턴스 수 반환
+   */
+  static getInstanceCount(): number {
+    return this.instances.size;
+  }
+
+  /**
+   * 디버깅용: 모든 인스턴스 정보 반환
+   */
+  static debug(): {
+    instanceCount: number;
+    configKeys: string[];
+    instances: Map<string, Translator>;
+  } {
+    return {
+      instanceCount: this.instances.size,
+      configKeys: Array.from(this.instances.keys()),
+      instances: this.instances,
+    };
+  }
+}