locai 2.1.0

package/dist/utils/logger.js

@@ -0,0 +1,374 @@
+/**
+ * Advanced Logging System.
+ * Implements saveErrorLogs, logDirectory, logRotation, and other logging features.
+ */
+import path from "path";
+import { promises as fsPromises } from "fs";
+class Logger {
+    config;
+    logFiles;
+    currentLogSizes;
+    initialized;
+    /**
+     * Create a new Logger instance.
+     * @param config - Logger configuration.
+     */
+    constructor(config = {}) {
+        this.config = {
+            verbose: config.verbose || false,
+            diagnosticsLevel: config.diagnosticsLevel || "minimal",
+            outputFormat: config.outputFormat || "pretty",
+            saveErrorLogs: config.saveErrorLogs !== false,
+            logDirectory: config.logDirectory || "./logs",
+            includeTimestamps: config.includeTimestamps !== false,
+            logRotation: {
+                enabled: config.logRotation?.enabled !== false,
+                maxFiles: config.logRotation?.maxFiles || 5,
+                maxSize: this.parseSize(config.logRotation?.maxSize || "10MB"),
+            },
+        };
+        this.logFiles = {
+            error: path.join(this.config.logDirectory, "errors.log"),
+            warning: path.join(this.config.logDirectory, "warnings.log"),
+            info: path.join(this.config.logDirectory, "info.log"),
+            debug: path.join(this.config.logDirectory, "debug.log"),
+        };
+        this.currentLogSizes = {};
+        this.initialized = false;
+    }
+    /**
+     * Initialize logger (create directories, check rotation).
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        try {
+            // Create log directory if it doesn't exist
+            if (this.config.saveErrorLogs) {
+                await fsPromises.mkdir(this.config.logDirectory, { recursive: true });
+                // Check log rotation for existing files
+                if (this.config.logRotation.enabled) {
+                    await this.checkAndRotateLogs();
+                }
+            }
+            this.initialized = true;
+        }
+        catch (error) {
+            console.warn(`Logger initialization warning: ${error.message}`);
+        }
+    }
+    /**
+     * Parse size string (e.g., "10MB") to bytes.
+     * @param sizeStr - Size string to parse.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    parseSize(sizeStr) {
+        if (typeof sizeStr === "number")
+            return sizeStr;
+        if (typeof sizeStr !== "string")
+            return 10 * 1024 * 1024;
+        const units = {
+            B: 1,
+            KB: 1024,
+            MB: 1024 * 1024,
+            GB: 1024 * 1024 * 1024,
+        };
+        const match = sizeStr.match(/^(\d+(?:\.\d+)?)\s*([A-Z]+)$/i);
+        if (!match)
+            return 10 * 1024 * 1024; // Default 10MB
+        const [, size, unit] = match;
+        return parseFloat(size) * (units[unit.toUpperCase()] || 1);
+    }
+    /**
+     * Check and rotate logs if needed.
+     */
+    async checkAndRotateLogs() {
+        for (const [level, logPath] of Object.entries(this.logFiles)) {
+            try {
+                const stats = await fsPromises.stat(logPath);
+                this.currentLogSizes[level] = stats.size;
+                if (stats.size >= this.config.logRotation.maxSize) {
+                    await this.rotateLog(logPath);
+                }
+            }
+            catch (error) {
+                console.warn(`Log rotation failed for ${logPath}: ${error.message}`);
+                this.currentLogSizes[level] = 0;
+            }
+        }
+    }
+    /**
+     * Rotate a log file.
+     * @param logPath - Path to the log file.
+     */
+    async rotateLog(logPath) {
+        try {
+            const dir = path.dirname(logPath);
+            const basename = path.basename(logPath, ".log");
+            const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+            // Rename current log
+            const archivedPath = path.join(dir, `${basename}.${timestamp}.log`);
+            await fsPromises.rename(logPath, archivedPath);
+            // Clean up old logs if exceeding maxFiles
+            await this.cleanupOldLogs(dir, basename);
+            // Reset size tracker
+            const level = Object.keys(this.logFiles).find((key) => this.logFiles[key] === logPath);
+            if (level) {
+                this.currentLogSizes[level] = 0;
+            }
+        }
+        catch (error) {
+            console.warn(`Log rotation failed for ${logPath}: ${error.message}`);
+        }
+    }
+    /**
+     * Clean up old log files.
+     * @param dir - Directory containing log files.
+     * @param basename - Basename of the log file.
+     */
+    async cleanupOldLogs(dir, basename) {
+        try {
+            const files = await fsPromises.readdir(dir);
+            const logFiles = files
+                .filter((file) => file.startsWith(basename) && file.endsWith(".log"))
+                .map((file) => ({
+                name: file,
+                path: path.join(dir, file),
+            }));
+            // Sort by modification time
+            const fileStats = await Promise.all(logFiles.map(async (file) => ({
+                ...file,
+                stats: await fsPromises.stat(file.path),
+            })));
+            fileStats.sort((a, b) => b.stats.mtime.getTime() - a.stats.mtime.getTime());
+            // Delete oldest files if exceeding maxFiles
+            if (fileStats.length > this.config.logRotation.maxFiles) {
+                const filesToDelete = fileStats.slice(this.config.logRotation.maxFiles);
+                for (const file of filesToDelete) {
+                    await fsPromises.unlink(file.path);
+                }
+            }
+        }
+        catch (error) {
+            console.warn(`Cleanup old logs failed: ${error.message}`);
+        }
+    }
+    /**
+     * Format log message.
+     * @param level - Log level.
+     * @param message - Log message.
+     * @param data - Additional data to log.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    formatMessage(level, message, data = null) {
+        const timestamp = this.config.includeTimestamps ? new Date().toISOString() : null;
+        switch (this.config.outputFormat) {
+            case "json":
+                return JSON.stringify({
+                    timestamp,
+                    level,
+                    message,
+                    data,
+                });
+            case "simple":
+                return `[${level.toUpperCase()}] ${message}`;
+            case "pretty":
+            default: {
+                const timeStr = timestamp ? `[${timestamp}] ` : "";
+                const levelStr = `[${level.toUpperCase()}]`;
+                const dataStr = data ? `\n${JSON.stringify(data, null, 2)}` : "";
+                return `${timeStr}${levelStr} ${message}${dataStr}`;
+            }
+        }
+    }
+    /**
+     * Write to log file.
+     * @param level - Log level.
+     * @param message - Log message.
+     * @param data - Additional data to log.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async writeToFile(level, message, data = null) {
+        if (!this.config.saveErrorLogs)
+            return;
+        await this.initialize();
+        const logPath = this.logFiles[level];
+        if (!logPath)
+            return;
+        try {
+            const formattedMessage = this.formatMessage(level, message, data);
+            const logEntry = `${formattedMessage}\n`;
+            await fsPromises.appendFile(logPath, logEntry, "utf8");
+            // Update size tracker
+            this.currentLogSizes[level] = (this.currentLogSizes[level] || 0) + logEntry.length;
+            // Check if rotation is needed
+            if (this.config.logRotation.enabled &&
+                this.currentLogSizes[level] >= this.config.logRotation.maxSize) {
+                await this.rotateLog(logPath);
+            }
+        }
+        catch (error) {
+            console.warn(`Failed to write to log file: ${error.message}`);
+        }
+    }
+    /**
+     * Simple console log with debug awareness.
+     * @param message - Message to log
+     * @param debugOnly - Only log if debug mode is enabled
+     */
+    async log(message, debugOnly = false) {
+        if (debugOnly && !this.config.verbose && !process.env.DEBUG) {
+            return;
+        }
+        console.log(message);
+    }
+    /**
+     * Log error.
+     * @param message - Error message.
+     * @param data - Additional data.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async error(message, data = null) {
+        console.error(`ERROR: ${message}`);
+        if (data && this.config.verbose) {
+            console.error(data);
+        }
+        await this.writeToFile("error", message, data);
+    }
+    /**
+     * Log warning.
+     * @param message - Warning message.
+     * @param data - Additional data.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async warn(message, data = null) {
+        console.warn(`WARNING: ${message}`);
+        if (data && this.config.verbose) {
+            console.warn(data);
+        }
+        await this.writeToFile("warning", message, data);
+    }
+    /**
+     * Log info.
+     * @param message - Info message.
+     * @param data - Additional data.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async info(message, data = null) {
+        if (this.config.diagnosticsLevel !== "minimal" || this.config.verbose) {
+            console.log(`INFO: ${message}`);
+            if (data && this.config.verbose) {
+                console.log(data);
+            }
+        }
+        await this.writeToFile("info", message, data);
+    }
+    /**
+     * Log debug.
+     * @param message - Debug message.
+     * @param data - Additional data.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async debug(message, data = null) {
+        if (this.config.verbose || this.config.diagnosticsLevel === "detailed") {
+            console.log(`DEBUG: ${message}`);
+            if (data) {
+                console.log(data);
+            }
+        }
+        await this.writeToFile("debug", message, data);
+    }
+    /**
+     * Log based on diagnostics level.
+     * @param level - Log level.
+     * @param message - Log message.
+     * @param data - Additional data.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async diagnostics(level, message, data = null) {
+        const levels = {
+            minimal: 1,
+            normal: 2,
+            detailed: 3,
+        };
+        const currentLevel = levels[this.config.diagnosticsLevel] || 1;
+        const messageLevel = levels[level] || 2;
+        if (messageLevel <= currentLevel) {
+            await this.info(message, data);
+        }
+    }
+    /**
+     * Get log statistics.
+     * @returns Object containing log stats.
+     */
+    async getLogStats() {
+        const stats = {};
+        for (const [level, logPath] of Object.entries(this.logFiles)) {
+            try {
+                const fileStats = await fsPromises.stat(logPath);
+                stats[level] = {
+                    size: fileStats.size,
+                    sizeFormatted: this.formatSize(fileStats.size),
+                    modified: fileStats.mtime,
+                };
+            }
+            catch (error) {
+                console.warn(`Failed to get stats for ${logPath}: ${error.message}`);
+                stats[level] = {
+                    size: 0,
+                    sizeFormatted: "0 B",
+                    modified: null,
+                };
+            }
+        }
+        return stats;
+    }
+    /**
+     * Format size to human-readable.
+     * @param bytes - Size in bytes.
+     */
+    formatSize(bytes) {
+        const units = ["B", "KB", "MB", "GB"];
+        let size = bytes;
+        let unitIndex = 0;
+        while (size >= 1024 && unitIndex < units.length - 1) {
+            size /= 1024;
+            unitIndex++;
+        }
+        return `${size.toFixed(2)} ${units[unitIndex]}`;
+    }
+    /**
+     * Clear all logs.
+     */
+    async clearLogs() {
+        for (const logPath of Object.values(this.logFiles)) {
+            try {
+                await fsPromises.unlink(logPath);
+            }
+            catch (error) {
+                console.warn(`Failed to clear log ${logPath}: ${error.message}`);
+            }
+        }
+        this.currentLogSizes = {};
+    }
+}
+// Create singleton instance
+let loggerInstance = null;
+export function getLogger(config = null) {
+    if (!loggerInstance || config) {
+        loggerInstance = new Logger(config || {});
+    }
+    return loggerInstance;
+}
+/**
+ * Quick debug-aware logging helper.
+ * @param message - Message to log.
+ * @param debugOnly - Only log in debug/verbose mode.
+ */
+export function log(message, debugOnly = false) {
+    if (debugOnly && !process.env.DEBUG && !process.env.VERBOSE) {
+        return;
+    }
+    console.log(message);
+}
+export default Logger;

package/dist/utils/object-transformer.js

@@ -0,0 +1,177 @@
+/**
+ * Utility class for object manipulation.
+ */
+class ObjectTransformer {
+    /**
+     * Flatten a nested object into a single-level object with dot notation keys.
+     * @param obj - The object to flatten.
+     * @param prefix - Prefix for keys (used internally).
+     * @param maxDepth - Maximum recursion depth.
+     * @returns Flattened object.
+     */
+    static flatten(obj, prefix = "", maxDepth = 20) {
+        if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return prefix ? { [prefix]: obj } : {};
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const result = {};
+        const stack = [{ obj, prefix, depth: 0 }];
+        while (stack.length > 0) {
+            const stackItem = stack.pop();
+            if (!stackItem)
+                continue;
+            const { obj: currentObj, prefix: currentPrefix, depth } = stackItem;
+            if (depth > maxDepth) {
+                result[currentPrefix] = "[Object too deep]";
+                continue;
+            }
+            const keys = Object.keys(currentObj);
+            const keysLength = keys.length;
+            for (let i = 0; i < keysLength; i++) {
+                const key = keys[i];
+                const value = currentObj[key];
+                const newKey = currentPrefix ? `${currentPrefix}.${key}` : key;
+                if (value !== null &&
+                    typeof value === "object" &&
+                    !Array.isArray(value) &&
+                    value.constructor === Object) {
+                    stack.push({ obj: value, prefix: newKey, depth: depth + 1 });
+                }
+                else {
+                    result[newKey] = value;
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Unflatten an object with dot notation keys into a nested object.
+     * @param obj - The flattened object.
+     * @returns Nested object.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static unflatten(obj) {
+        if (!obj || typeof obj !== "object") {
+            return {};
+        }
+        const result = {};
+        const keys = Object.keys(obj);
+        const keysLength = keys.length;
+        keys.sort();
+        for (let keyIndex = 0; keyIndex < keysLength; keyIndex++) {
+            const key = keys[keyIndex];
+            const value = obj[key];
+            const keyParts = key.split(".");
+            const partsLength = keyParts.length;
+            if (partsLength === 0)
+                continue;
+            let hasEmptyPart = false;
+            for (let i = 0; i < partsLength; i++) {
+                if (keyParts[i] === "") {
+                    hasEmptyPart = true;
+                    break;
+                }
+            }
+            if (hasEmptyPart)
+                continue;
+            let current = result;
+            const lastIndex = partsLength - 1;
+            for (let i = 0; i < lastIndex; i++) {
+                const part = keyParts[i];
+                if (current[part] == null ||
+                    typeof current[part] !== "object" ||
+                    Array.isArray(current[part])) {
+                    current[part] = {};
+                }
+                current = current[part];
+            }
+            current[keyParts[lastIndex]] = value;
+        }
+        return result;
+    }
+    /**
+     * Create a deep copy of an object.
+     * @param obj - The object to clone.
+     * @param seen - Internal set to track circular references.
+     * @returns Deep copy of the object.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static deepClone(obj, seen = new WeakSet()) {
+        if (obj === null || typeof obj !== "object") {
+            return obj;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (seen.has(obj)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return {};
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        seen.add(obj);
+        if (Array.isArray(obj)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const result = obj.map((item) => this.deepClone(item, seen));
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            seen.delete(obj);
+            return result;
+        }
+        if (obj instanceof Date) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            seen.delete(obj);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return new Date(obj.getTime());
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (obj.constructor !== Object) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            seen.delete(obj);
+            return obj;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const result = {};
+        for (const key of Object.keys(obj)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            result[key] = this.deepClone(obj[key], seen);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        seen.delete(obj);
+        return result;
+    }
+    /**
+     * deeply merge two objects.
+     * @param target - The target object.
+     * @param source - The source object.
+     * @param overwriteArrays - Whether to overwrite arrays or merge them.
+     * @returns Merged object.
+     */
+    static mergeObjects(target, source, overwriteArrays = false) {
+        if (!target || !source || typeof target !== "object" || typeof source !== "object") {
+            return target;
+        }
+        const result = this.deepClone(target);
+        for (const key of Object.keys(source)) {
+            const sourceValue = source[key];
+            const targetValue = result[key];
+            if (sourceValue === undefined) {
+                continue;
+            }
+            if (Array.isArray(sourceValue)) {
+                result[key] = overwriteArrays
+                    ? [...sourceValue]
+                    : Array.isArray(targetValue)
+                        ? [...targetValue, ...sourceValue]
+                        : [...sourceValue];
+            }
+            else if (sourceValue &&
+                typeof sourceValue === "object" &&
+                sourceValue.constructor === Object) {
+                result[key] = this.mergeObjects(targetValue || {}, sourceValue, overwriteArrays);
+            }
+            else {
+                result[key] = sourceValue;
+            }
+        }
+        return result;
+    }
+}
+export default ObjectTransformer;