@umituz/web-localization 1.1.8 → 1.1.9

package/dist/infrastructure/utils/file.util.js

@@ -1,22 +1,91 @@
 import fs from "fs";
+import path from "path";
+const fileCache = new Map();
+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) {
+    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 null;
+    }
+    // Read file content
+    const content = fs.readFileSync(resolvedPath, "utf-8");
+    // Add to cache (evict oldest if cache is full)
+    if (fileCache.size >= MAX_CACHE_SIZE) {
+        let oldestKey = 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 Simplistic parser for 'export default { ... }' or 'export const data = { ... }'
+ * @description Improved parser with caching and better error handling
+ * @security Note: Uses Function constructor - only use with trusted local files
  */
 export function parseTypeScriptFile(filePath) {
-    if (!fs.existsSync(filePath))
+    const content = getFileContent(filePath);
+    if (!content)
         return {};
-    const content = fs.readFileSync(filePath, "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)
+    // Try to match export patterns (pre-compiled for performance)
+    let match = 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) {
@@ -26,11 +95,11 @@ export function parseTypeScriptFile(filePath) {
 }
 /**
  * Generates a TypeScript file content from an object
+ * @description Optimized content generation with proper escaping
  */
 export function generateTypeScriptContent(obj, langCode) {
+    // 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
@@ -39,3 +108,73 @@ export function generateTypeScriptContent(obj, langCode) {
 export default ${jsonStr};
 `;
 }
+/**
+ * Clear file content cache
+ * @description Call this when you know files have been modified externally
+ */
+export function clearFileCache() {
+    fileCache.clear();
+}
+/**
+ * Get cache statistics
+ */
+export function getFileCacheStats() {
+    return {
+        size: fileCache.size,
+        maxSize: MAX_CACHE_SIZE,
+    };
+}
+/**
+ * Check if a file exists (async version for better performance)
+ */
+export async function fileExists(filePath) {
+    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) {
+    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, content) {
+    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/dist/infrastructure/utils/rate-limit.util.d.ts

@@ -1,10 +1,43 @@
 /**
- * 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
  */
 export declare class RateLimiter {
     private lastRequestTime;
-    private minDelay;
+    private readonly minDelay;
+    private queue;
+    private processingQueue;
+    private dynamicDelay;
+    private responseTimeHistory;
+    private readonly maxHistorySize;
     constructor(minDelay?: number);
-    waitForSlot(): Promise<void>;
+    /**
+     * Wait for available slot with priority support
+     * @param priority - Lower number = higher priority (default: 10)
+     */
+    waitForSlot(priority?: number): Promise<void>;
+    /**
+     * Process queued requests with controlled timing
+     */
+    private processQueue;
+    /**
+     * Record response time for dynamic delay adjustment
+     */
+    recordResponseTime(responseTimeMs: number): void;
+    /**
+     * Reset dynamic delay to minimum
+     */
+    resetDynamicDelay(): void;
+    /**
+     * Get current queue length
+     */
+    getQueueLength(): number;
+    /**
+     * Optimized sleep function
+     */
+    private sleep;
+    /**
+     * Clear all pending requests (for cleanup)
+     */
+    clear(): void;
 }

package/dist/infrastructure/utils/rate-limit.util.js

@@ -1,20 +1,119 @@
 /**
- * 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 { DEFAULT_MIN_DELAY } from "../constants/index.js";
 export class RateLimiter {
     lastRequestTime = 0;
     minDelay;
-    constructor(minDelay = 100) {
+    queue = [];
+    processingQueue = false;
+    dynamicDelay;
+    responseTimeHistory = [];
+    maxHistorySize = 10;
+    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) {
+        // 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((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
+     */
+    async processQueue() {
+        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() {
-        const now = Date.now();
-        const elapsedTime = now - this.lastRequestTime;
-        if (elapsedTime < this.minDelay) {
-            const waitTime = this.minDelay - elapsedTime;
-            await new Promise(resolve => setTimeout(resolve, waitTime));
+    /**
+     * Record response time for dynamic delay adjustment
+     */
+    recordResponseTime(responseTimeMs) {
+        this.responseTimeHistory.push(responseTimeMs);
+        // Keep history size bounded
+        if (this.responseTimeHistory.length > this.maxHistorySize) {
+            this.responseTimeHistory.shift();
         }
-        this.lastRequestTime = Date.now();
+        // 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() {
+        this.dynamicDelay = this.minDelay;
+        this.responseTimeHistory = [];
+    }
+    /**
+     * Get current queue length
+     */
+    getQueueLength() {
+        return this.queue.length;
+    }
+    /**
+     * Optimized sleep function
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Clear all pending requests (for cleanup)
+     */
+    clear() {
+        this.queue = [];
+        this.processingQueue = false;
     }
 }

package/dist/infrastructure/utils/text-validator.util.d.ts

@@ -12,4 +12,4 @@ export declare function shouldSkipWord(text: string): boolean;
 /**
  * Determines if a key needs translation
  */
-export declare function needsTranslation(targetValue: unknown, sourceValue: string): boolean;
+export declare function needsTranslation(targetValue: unknown): boolean;

package/dist/infrastructure/utils/text-validator.util.js

@@ -1,6 +1,8 @@
 /**
  * Text Validation Utilities
  */
+// Default words/patterns to skip during translation
+const DEFAULT_SKIPLIST = ["@umituz"];
 /**
  * Validates if the text is suitable for translation
  */
@@ -17,17 +19,15 @@ export function isValidText(text) {
  * Checks if a word should be skipped (e.g., proper nouns, symbols)
  */
 export function shouldSkipWord(text) {
-    const skiplist = ["@umituz"];
-    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, sourceValue) {
+export function needsTranslation(targetValue) {
     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/dist/integrations/i18n.setup.d.ts

@@ -1,22 +1,60 @@
 import i18n from 'i18next';
+export interface DetectionOptions {
+    order?: string[];
+    caches?: string[];
+    lookupLocalStorage?: string;
+    lookupSessionstorage?: string;
+}
 export interface SetupI18nOptions {
     resources: Record<string, {
-        translation: any;
+        translation: Record<string, unknown>;
     }>;
     defaultLng?: string;
     fallbackLng?: string;
     onInit?: (instance: typeof i18n) => void;
-    detection?: any;
+    detection?: DetectionOptions;
     seo?: {
         titleKey: string;
         descriptionKey: string;
         defaultImage?: string;
         twitterHandle?: string;
     };
+    lazyLoad?: boolean;
+    cache?: boolean;
 }
 /**
- * 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 declare function setupI18n(options: SetupI18nOptions): typeof i18n;
+/**
+ * Add language dynamically (for lazy loading scenarios)
+ * @description Efficiently adds new language resources without full re-initialization
+ */
+export declare function addLanguage(lng: string, resources: Record<string, unknown>, ns?: string): void;
+/**
+ * Change language with performance optimization
+ * @description Changes language efficiently without unnecessary re-renders
+ */
+export declare function changeLanguage(lng: string): Promise<void>;
+/**
+ * Get current language
+ */
+export declare function getCurrentLanguage(): string;
+/**
+ * Check if i18n is initialized
+ */
+export declare function isI18nInitialized(): boolean;
+/**
+ * Reset i18n instance (for testing or cleanup)
+ * @description Note: i18next doesn't have a built-in reset method, this clears tracking state
+ */
+export declare function resetI18n(): void;
+/**
+ * Get i18n instance
  */
-export declare function setupI18n(options: SetupI18nOptions): import("i18next").i18n;
-export default i18n;
+export declare function getI18nInstance(): typeof i18n;

package/dist/integrations/i18n.setup.js

@@ -2,37 +2,164 @@ import i18n from 'i18next';
 import { initReactI18next } from 'react-i18next';
 import LanguageDetector from 'i18next-browser-languagedetector';
 import { initSEO } from '@umituz/web-seo';
+// Initialization state tracking
+let isInitialized = false;
+let initializationPromise = 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) {
+    // 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', fallbackLng = 'en-US', onInit, detection = {
         order: ['localStorage', 'navigator'],
         caches: ['localStorage'],
-    }, seo, } = options;
-    i18n
+    }, seo, lazyLoad = false, cache = true, } = options;
+    // 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: {
+            ...detection,
+            // Cache detection results
+            caches: detection.caches || ['localStorage'],
+        },
+        // 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;
 }
-export default i18n;
+/**
+ * Optimize resources structure for better performance
+ * @description Removes duplicate keys and flattens nested structures where beneficial
+ */
+function optimizeResources(resources) {
+    const optimized = {};
+    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, resources, ns = 'translation') {
+    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) {
+    if (!i18n.isInitialized) {
+        console.warn('i18n is not initialized yet. Call setupI18n first.');
+        return;
+    }
+    await i18n.changeLanguage(lng);
+}
+/**
+ * Get current language
+ */
+export function getCurrentLanguage() {
+    return i18n.language || i18n.languages[0] || 'en-US';
+}
+/**
+ * Check if i18n is initialized
+ */
+export function isI18nInitialized() {
+    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() {
+    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() {
+    return i18n;
+}

package/dist/scripts/cli.js

@@ -5,11 +5,16 @@
 import { Command } from "commander";
 import { cliService } from "../infrastructure/services/cli.service.js";
 import chalk from "chalk";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJson = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf-8"));
 const program = new Command();
 program
     .name("web-loc")
     .description("Localization CLI tool for web applications")
-    .version("1.0.0");
+    .version(packageJson.version);
 program
     .command("sync")
     .description("Synchronize missing keys from base language to other languages")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-localization",
-  "version": "1.1.8",
+  "version": "1.1.9",
   "description": "Google Translate integrated localization package for web applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -39,7 +39,7 @@
     "i18next": "^23.11.2",
     "react-i18next": "^14.1.1",
     "i18next-browser-languagedetector": "^7.2.1",
-    "@umituz/web-seo": "file:../web-seo"
+    "@umituz/web-seo": "^2.0.15"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",