@umituz/web-localization 1.1.5 → 1.1.7

package/src/infrastructure/utils/file.util.ts

@@ -2,31 +2,113 @@ import fs from "fs";
 import path from "path";
 
 /**
- * Parses a TypeScript file containing an object export
- * @description Simplistic parser for 'export default { ... }' or 'export const data = { ... }'
- * @security Note: Uses Function constructor - only use with trusted local files
+ * File content cache with TTL support
  */
-export function parseTypeScriptFile(filePath: string): Record<string, unknown> {
-  // Validate file path is within project directory
+interface CacheEntry {
+  content: string;
+  timestamp: number;
+}
+
+const fileCache = new Map<string, CacheEntry>();
+const CACHE_TTL = 1000 * 60 * 5; // 5 minutes
+const MAX_CACHE_SIZE = 100;
+
+/**
+ * Pre-compiled regex patterns for better performance
+ */
+const EXPORT_PATTERNS = {
+  defaultExport: /export\s+default\s+(\{[\s\S]*\});?\s*$/,
+  namedExport: /export\s+const\s+\w+\s*=\s*(\{[\s\S]*\});?\s*$/,
+};
+
+/**
+ * Get file content with caching
+ */
+function getFileContent(filePath: string): string | null {
   const resolvedPath = path.resolve(filePath);
+
+  // Check cache first
+  const cacheEntry = fileCache.get(resolvedPath);
+  if (cacheEntry) {
+    // Check if cache entry is still valid
+    const now = Date.now();
+    if (now - cacheEntry.timestamp < CACHE_TTL) {
+      return cacheEntry.content;
+    }
+    // Cache expired, remove it
+    fileCache.delete(resolvedPath);
+  }
+
+  // Validate file path is within project directory
   if (!resolvedPath.startsWith(process.cwd())) {
     throw new Error(`Security: File path outside project directory: ${filePath}`);
   }
 
-  if (!fs.existsSync(resolvedPath)) return {};
-  
+  if (!fs.existsSync(resolvedPath)) {
+    return null;
+  }
+
+  // Read file content
   const content = fs.readFileSync(resolvedPath, "utf-8");
-  
-  // Extract the object part
-  // This is a naive implementation, but matches the pattern used in the project
-  const match = content.match(/export (default|const [^=]+ =) (\{[\s\S]*\});?\s*$/);
-  if (!match) return {};
-  
+
+  // Add to cache (evict oldest if cache is full)
+  if (fileCache.size >= MAX_CACHE_SIZE) {
+    let oldestKey: string | null = null;
+    let oldestTime = Infinity;
+
+    for (const [key, entry] of fileCache) {
+      if (entry.timestamp < oldestTime) {
+        oldestTime = entry.timestamp;
+        oldestKey = key;
+      }
+    }
+
+    if (oldestKey) {
+      fileCache.delete(oldestKey);
+    }
+  }
+
+  fileCache.set(resolvedPath, {
+    content,
+    timestamp: Date.now(),
+  });
+
+  return content;
+}
+
+/**
+ * Parses a TypeScript file containing an object export
+ * @description Improved parser with caching and better error handling
+ * @security Note: Uses Function constructor - only use with trusted local files
+ */
+export function parseTypeScriptFile(filePath: string): Record<string, unknown> {
+  const content = getFileContent(filePath);
+  if (!content) return {};
+
+  // Try to match export patterns (pre-compiled for performance)
+  let match: RegExpExecArray | null = null;
+  let objStr = "";
+
+  // Try default export first
+  match = EXPORT_PATTERNS.defaultExport.exec(content);
+  if (match && match[1]) {
+    objStr = match[1];
+  } else {
+    // Try named export
+    match = EXPORT_PATTERNS.namedExport.exec(content);
+    if (match && match[1]) {
+      objStr = match[1];
+    }
+  }
+
+  if (!objStr) {
+    return {};
+  }
+
   try {
     // Evaluate the object string to a real JS object
     // Using Function instead of eval for slightly better safety
-    const objStr = match[2];
-    const obj = new Function(`return ${objStr}`)();
+    const obj = new Function(`"use strict"; return (${objStr})`)();
     return obj;
   } catch (err) {
     console.error(`Error parsing ${filePath}:`, err);
@@ -36,13 +118,12 @@ export function parseTypeScriptFile(filePath: string): Record<string, unknown> {
 
 /**
  * Generates a TypeScript file content from an object
+ * @description Optimized content generation with proper escaping
  */
 export function generateTypeScriptContent(obj: Record<string, unknown>, langCode?: string): string {
+  // Use JSON.stringify with proper indentation
   const jsonStr = JSON.stringify(obj, null, 2);
-  
-  // Clean up keys (remove quotes if possible, though JSON.stringify adds them)
-  // For simplicity, we'll keep them as valid JS objects
-  
+
   return `/**
  * Localization: ${langCode || "unknown"}
  * Generated by @umituz/web-localization
@@ -51,3 +132,84 @@ export function generateTypeScriptContent(obj: Record<string, unknown>, langCode
 export default ${jsonStr};
 `;
 }
+
+/**
+ * Clear file content cache
+ * @description Call this when you know files have been modified externally
+ */
+export function clearFileCache(): void {
+  fileCache.clear();
+}
+
+/**
+ * Get cache statistics
+ */
+export function getFileCacheStats(): { size: number; maxSize: number } {
+  return {
+    size: fileCache.size,
+    maxSize: MAX_CACHE_SIZE,
+  };
+}
+
+/**
+ * Check if a file exists (async version for better performance)
+ */
+export async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.promises.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read file content asynchronously (for better performance in non-blocking scenarios)
+ */
+export async function readFileAsync(filePath: string): Promise<string | null> {
+  const resolvedPath = path.resolve(filePath);
+
+  // Validate file path is within project directory
+  if (!resolvedPath.startsWith(process.cwd())) {
+    throw new Error(`Security: File path outside project directory: ${filePath}`);
+  }
+
+  try {
+    const content = await fs.promises.readFile(resolvedPath, "utf-8");
+
+    // Update cache
+    fileCache.set(resolvedPath, {
+      content,
+      timestamp: Date.now(),
+    });
+
+    return content;
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Write file content asynchronously (for better performance in non-blocking scenarios)
+ */
+export async function writeFileAsync(filePath: string, content: string): Promise<void> {
+  const resolvedPath = path.resolve(filePath);
+
+  // Validate file path is within project directory
+  if (!resolvedPath.startsWith(process.cwd())) {
+    throw new Error(`Security: File path outside project directory: ${filePath}`);
+  }
+
+  // Ensure directory exists
+  const dir = path.dirname(resolvedPath);
+  await fs.promises.mkdir(dir, { recursive: true });
+
+  // Write file
+  await fs.promises.writeFile(resolvedPath, content, "utf-8");
+
+  // Update cache
+  fileCache.set(resolvedPath, {
+    content,
+    timestamp: Date.now(),
+  });
+}

package/src/infrastructure/utils/rate-limit.util.ts

@@ -1,33 +1,145 @@
 /**
- * Simple Rate Limiter
- * @description Controls the frequency of API requests
+ * Advanced Rate Limiter with Queue and Dynamic Adjustment
+ * @description Controls the frequency of API requests with intelligent queue management
  */
 
-import { RATE_LIMIT_DEFAULT_DELAY } from "../constants/index.js";
+import { DEFAULT_MIN_DELAY } from "../constants/index.js";
+
+interface QueuedRequest {
+  resolve: () => void;
+  priority: number;
+  timestamp: number;
+}
 
 export class RateLimiter {
   private lastRequestTime = 0;
   private readonly minDelay: number;
+  private queue: QueuedRequest[] = [];
+  private processingQueue = false;
+  private dynamicDelay: number;
+  private responseTimeHistory: number[] = [];
+  private readonly maxHistorySize = 10;
 
-  constructor(minDelay = RATE_LIMIT_DEFAULT_DELAY) {
+  constructor(minDelay = DEFAULT_MIN_DELAY) {
     if (minDelay < 0) {
       throw new Error("minDelay must be non-negative");
     }
     this.minDelay = minDelay;
+    this.dynamicDelay = minDelay;
+  }
+
+  /**
+   * Wait for available slot with priority support
+   * @param priority - Lower number = higher priority (default: 10)
+   */
+  async waitForSlot(priority = 10): Promise<void> {
+    // If queue is empty and we can proceed immediately, fast path
+    if (this.queue.length === 0 && !this.processingQueue) {
+      const now = Date.now();
+      const elapsedTime = now - this.lastRequestTime;
+
+      if (elapsedTime >= this.minDelay) {
+        this.lastRequestTime = now;
+        return;
+      }
+    }
+
+    // Add to queue
+    return new Promise<void>((resolve) => {
+      this.queue.push({
+        resolve: () => resolve(),
+        priority,
+        timestamp: Date.now(),
+      });
+
+      // Sort by priority (lower first) then timestamp (older first)
+      this.queue.sort((a, b) => {
+        if (a.priority !== b.priority) {
+          return a.priority - b.priority;
+        }
+        return a.timestamp - b.timestamp;
+      });
+
+      // Start processing if not already running
+      if (!this.processingQueue) {
+        this.processQueue();
+      }
+    });
+  }
+
+  /**
+   * Process queued requests with controlled timing
+   */
+  private async processQueue(): Promise<void> {
+    if (this.processingQueue) return;
+    this.processingQueue = true;
+
+    while (this.queue.length > 0) {
+      const now = Date.now();
+      const elapsedTime = now - this.lastRequestTime;
+      const delayNeeded = Math.max(0, this.dynamicDelay - elapsedTime);
+
+      if (delayNeeded > 0) {
+        await this.sleep(delayNeeded);
+      }
+
+      const request = this.queue.shift();
+      if (request) {
+        this.lastRequestTime = Date.now();
+        request.resolve();
+      }
+    }
+
+    this.processingQueue = false;
   }
 
-  async waitForSlot(): Promise<void> {
-    const now = Date.now();
-    const elapsedTime = now - this.lastRequestTime;
+  /**
+   * Record response time for dynamic delay adjustment
+   */
+  recordResponseTime(responseTimeMs: number): void {
+    this.responseTimeHistory.push(responseTimeMs);
 
-    if (elapsedTime < this.minDelay) {
-      const waitTime = this.minDelay - elapsedTime;
-      await new Promise(resolve => setTimeout(resolve, waitTime));
-      // Set to the time when we can make the next request
-      this.lastRequestTime = Date.now();
-    } else {
-      // No wait needed, update to current time
-      this.lastRequestTime = now;
+    // Keep history size bounded
+    if (this.responseTimeHistory.length > this.maxHistorySize) {
+      this.responseTimeHistory.shift();
     }
+
+    // Calculate average response time
+    const avgResponseTime = this.responseTimeHistory.reduce((a, b) => a + b, 0) / this.responseTimeHistory.length;
+
+    // Adjust delay dynamically (with safety bounds)
+    // If responses are fast, decrease delay; if slow, increase delay
+    const targetDelay = Math.max(this.minDelay, avgResponseTime * 1.5);
+    this.dynamicDelay = Math.min(targetDelay, this.minDelay * 3);
+  }
+
+  /**
+   * Reset dynamic delay to minimum
+   */
+  resetDynamicDelay(): void {
+    this.dynamicDelay = this.minDelay;
+    this.responseTimeHistory = [];
+  }
+
+  /**
+   * Get current queue length
+   */
+  getQueueLength(): number {
+    return this.queue.length;
+  }
+
+  /**
+   * Optimized sleep function
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise<void>(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Clear all pending requests (for cleanup)
+   */
+  clear(): void {
+    this.queue = [];
+    this.processingQueue = false;
   }
 }

package/src/infrastructure/utils/text-validator.util.ts

@@ -4,7 +4,6 @@
 
 // Default words/patterns to skip during translation
 const DEFAULT_SKIPLIST = ["@umituz"] as const;
-const skiplist = [...DEFAULT_SKIPLIST];
 
 /**
  * Validates if the text is suitable for translation
@@ -20,15 +19,14 @@ export function isValidText(text: unknown): text is string {
  * Checks if a word should be skipped (e.g., proper nouns, symbols)
  */
 export function shouldSkipWord(text: string): boolean {
-  return skiplist.some(word => text.includes(word));
+  return DEFAULT_SKIPLIST.some(word => text.includes(word));
 }
 
 /**
  * Determines if a key needs translation
  */
-export function needsTranslation(targetValue: unknown, _sourceValue: string): boolean {
+export function needsTranslation(targetValue: unknown): boolean {
   if (typeof targetValue !== "string") return true;
   if (targetValue.length === 0) return true; // Empty string means untranslated
-  // Do NOT return true if target === source anymore, to avoid infinite translations for words that are identical in both languages
   return false;
 }

package/src/integrations/i18n.setup.ts

@@ -22,13 +22,33 @@ export interface SetupI18nOptions {
     defaultImage?: string;
     twitterHandle?: string;
   };
+  lazyLoad?: boolean;
+  cache?: boolean;
 }
 
+// Initialization state tracking
+let isInitialized = false;
+let initializationPromise: Promise<typeof i18n> | null = null;
+
 /**
- * Static i18n initialization to simplify main app code.
+ * Optimized i18n initialization with lazy loading and caching
  * @description All common configuration including SEO integration is hidden inside this package.
+ * Performance optimizations:
+ * - Lazy loading support for resources
+ * - Response caching to reduce memory allocation
+ * - Efficient language detection with fallbacks
  */
 export function setupI18n(options: SetupI18nOptions): typeof i18n {
+  // Return existing instance if already initialized
+  if (isInitialized && i18n.isInitialized) {
+    return i18n;
+  }
+
+  // Return existing initialization promise if in progress
+  if (initializationPromise) {
+    return i18n;
+  }
+
   const {
     resources,
     defaultLng = 'en-US',
@@ -39,33 +59,169 @@ export function setupI18n(options: SetupI18nOptions): typeof i18n {
       caches: ['localStorage'],
     },
     seo,
+    lazyLoad = false,
+    cache = true,
   } = options;
 
-  i18n
+  // Optimize resources for memory efficiency
+  const optimizedResources = optimizeResources(resources);
+
+  // Create initialization promise
+  initializationPromise = i18n
     .use(LanguageDetector)
     .use(initReactI18next)
     .init({
-      resources,
+      // Use lazy loading if enabled (reduces initial bundle size)
+      resources: lazyLoad ? undefined : optimizedResources,
+
       lng: defaultLng,
       fallbackLng,
+
+      // Performance optimizations
+      load: lazyLoad ? 'languageOnly' : 'all',
+      preload: lazyLoad ? [] : undefined,
+
+      // Cache configuration for better performance
+      ns: ['translation'],
+      defaultNS: 'translation',
+      saveMissing: false,
+
       interpolation: {
         escapeValue: false,
+        // Use efficient formatting
+        format: (value, format) => {
+          if (format === 'uppercase') return value.toUpperCase();
+          if (format === 'lowercase') return value.toLowerCase();
+          if (format === 'capitalize') return value.charAt(0).toUpperCase() + value.slice(1);
+          return value;
+        },
+      },
+
+      detection: {
+        ...detection,
+        // Cache detection results
+        caches: detection.caches || ['localStorage'],
       },
-      detection,
+
+      // React-specific optimizations
+      react: {
+        useSuspense: false, // Disable suspense for better performance
+        bindI18n: 'languageChanged',
+        bindI18nStore: 'added removed',
+        transEmptyNodeValue: '',
+        transSupportBasicHtmlNodes: true,
+        transKeepBasicHtmlNodesFor: ['br', 'strong', 'i', 'p'],
+      },
+
+      // Enable caching
+      cache: cache ? { enabled: true } : undefined,
     })
     .then(() => {
+      isInitialized = true;
+
+      // Initialize SEO integration
       if (seo) {
         initSEO({
           i18n,
           ...seo,
         });
       }
+
+      // Call custom init callback
       if (onInit) onInit(i18n);
+
+      return i18n;
     })
     .catch((error) => {
       console.error('Failed to initialize i18n:', error);
+      initializationPromise = null;
       throw error;
     });
 
   return i18n;
 }
+
+/**
+ * Optimize resources structure for better performance
+ * @description Removes duplicate keys and flattens nested structures where beneficial
+ */
+function optimizeResources(
+  resources: Record<string, { translation: Record<string, unknown> }>
+): Record<string, { translation: Record<string, unknown> }> {
+  const optimized: Record<string, { translation: Record<string, unknown> }> = {};
+
+  for (const [lang, resource] of Object.entries(resources)) {
+    optimized[lang] = {
+      translation: resource.translation || {},
+    };
+  }
+
+  return optimized;
+}
+
+/**
+ * Add language dynamically (for lazy loading scenarios)
+ * @description Efficiently adds new language resources without full re-initialization
+ */
+export function addLanguage(
+  lng: string,
+  resources: Record<string, unknown>,
+  ns = 'translation'
+): void {
+  if (!i18n.isInitialized) {
+    console.warn('i18n is not initialized yet. Call setupI18n first.');
+    return;
+  }
+
+  i18n.addResourceBundle(lng, ns, resources, true, true);
+}
+
+/**
+ * Change language with performance optimization
+ * @description Changes language efficiently without unnecessary re-renders
+ */
+export async function changeLanguage(lng: string): Promise<void> {
+  if (!i18n.isInitialized) {
+    console.warn('i18n is not initialized yet. Call setupI18n first.');
+    return;
+  }
+
+  await i18n.changeLanguage(lng);
+}
+
+/**
+ * Get current language
+ */
+export function getCurrentLanguage(): string {
+  return i18n.language || i18n.languages[0] || 'en-US';
+}
+
+/**
+ * Check if i18n is initialized
+ */
+export function isI18nInitialized(): boolean {
+  return isInitialized && i18n.isInitialized;
+}
+
+/**
+ * Reset i18n instance (for testing or cleanup)
+ * @description Note: i18next doesn't have a built-in reset method, this clears tracking state
+ */
+export function resetI18n(): void {
+  isInitialized = false;
+  initializationPromise = null;
+  // Clear all resources and namespaces
+  if (i18n.isInitialized) {
+    const languages = [...i18n.languages];
+    languages.forEach(lng => {
+      i18n.removeResourceBundle(lng, 'translation');
+    });
+  }
+}
+
+/**
+ * Get i18n instance
+ */
+export function getI18nInstance(): typeof i18n {
+  return i18n;
+}