@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/esm/provider/logger/transports/file.transport.js

@@ -0,0 +1,291 @@
+import { LogLevel, shouldLog } from "../utils/log-levels.js";
+import { formatProd } from "../logger.formatter.js";
+import { promises as fs } from "fs";
+import { join } from "path";
+import { createGzip } from "zlib";
+import { pipeline } from "stream/promises";
+import { createReadStream, createWriteStream } from "fs";
+/**
+ * File transport for logging to files with daily rotation and advanced features.
+ * @public API
+ */
+export class FileTransport {
+    name = "File";
+    level; // Mutable to allow dynamic level updates
+    enabled;
+    directory;
+    filenamePattern;
+    compress;
+    maxSize;
+    maxAge;
+    maxFiles;
+    currentFilename = null;
+    currentFileSize = 0;
+    cleanupInterval = null;
+    constructor(options) {
+        this.level = options?.level ?? LogLevel.INFO;
+        this.enabled = options?.enabled ?? true;
+        this.directory = options?.directory ?? "logs";
+        this.filenamePattern = options?.filename ?? "app-%DATE%.log";
+        this.compress = options?.compress ?? false;
+        this.maxSize = options?.maxSize ?? 0; // 0 = unlimited
+        this.maxAge = options?.maxAge ?? 0; // 0 = unlimited
+        this.maxFiles = options?.maxFiles ?? 0; // 0 = unlimited
+        // Start cleanup interval if maxAge or maxFiles is set
+        if (this.maxAge > 0 || this.maxFiles > 0) {
+            this.startCleanupInterval();
+        }
+    }
+    /**
+     * Create a file transport with daily rotation.
+     * @param options - Transport options
+     * @returns FileTransport configured for daily rotation
+     * @public API
+     */
+    static daily(options) {
+        return new FileTransport({
+            ...options,
+            filename: "app-%DATE%.log",
+        });
+    }
+    /**
+     * Create a file transport with compression enabled.
+     * @param options - Transport options
+     * @returns FileTransport with compression enabled
+     * @public API
+     */
+    static withCompression(options) {
+        return new FileTransport({
+            ...options,
+            compress: true,
+        });
+    }
+    /**
+     * Create a file transport with size-based rotation.
+     * @param maxSize - Maximum file size in bytes
+     * @param options - Transport options
+     * @returns FileTransport with size-based rotation
+     * @public API
+     */
+    static withMaxSize(maxSize, options) {
+        return new FileTransport({
+            ...options,
+            maxSize,
+        });
+    }
+    /**
+     * Create a file transport with retention policy.
+     * @param maxAge - Maximum file age in milliseconds
+     * @param maxFiles - Maximum number of files to keep
+     * @param options - Transport options
+     * @returns FileTransport with retention policy
+     * @public API
+     */
+    static withRetention(maxAge, maxFiles, options) {
+        return new FileTransport({
+            ...options,
+            maxAge,
+            maxFiles,
+        });
+    }
+    async log(entry) {
+        if (!this.enabled || !shouldLog(entry.level, this.level)) {
+            return;
+        }
+        const filename = this.getFilename();
+        const shouldRotate = this.shouldRotate(filename);
+        if (shouldRotate) {
+            await this.rotateFile(filename);
+        }
+        if (filename !== this.currentFilename) {
+            this.currentFilename = filename;
+            this.currentFileSize = await this.getFileSize(filename);
+        }
+        await this.ensureDirectory();
+        const filePath = join(this.directory, this.currentFilename);
+        const formatted = formatProd(entry) + "\n";
+        const entrySize = Buffer.byteLength(formatted, "utf8");
+        try {
+            await fs.appendFile(filePath, formatted, "utf8");
+            this.currentFileSize += entrySize;
+            // Check if we need to rotate after this write
+            if (this.maxSize > 0 && this.currentFileSize >= this.maxSize) {
+                await this.rotateFile(this.currentFilename);
+            }
+        }
+        catch (error) {
+            // Silently fail to avoid log loops
+            console.error(`[FileTransport] Failed to write log:`, error);
+        }
+    }
+    async flush() {
+        // File writes are synchronous, no flush needed
+        return Promise.resolve();
+    }
+    async close() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        this.currentFilename = null;
+        this.currentFileSize = 0;
+    }
+    getFilename() {
+        const today = new Date();
+        const dateStr = today.toISOString().split("T")[0]; // YYYY-MM-DD
+        return this.filenamePattern.replace("%DATE%", dateStr);
+    }
+    async ensureDirectory() {
+        try {
+            await fs.access(this.directory);
+        }
+        catch {
+            await fs.mkdir(this.directory, { recursive: true });
+        }
+    }
+    async getFileSize(filename) {
+        try {
+            const filePath = join(this.directory, filename);
+            const stats = await fs.stat(filePath);
+            return stats.size;
+        }
+        catch {
+            return 0;
+        }
+    }
+    shouldRotate(filename) {
+        // Rotate if filename changed (daily rotation)
+        if (filename !== this.currentFilename) {
+            return true;
+        }
+        // Rotate if size limit exceeded
+        if (this.maxSize > 0 && this.currentFileSize >= this.maxSize) {
+            return true;
+        }
+        return false;
+    }
+    async rotateFile(filename) {
+        const fileToRotate = filename || this.currentFilename;
+        if (!fileToRotate) {
+            return;
+        }
+        const oldFilePath = join(this.directory, fileToRotate);
+        const newFilename = this.getRotatedFilename(fileToRotate);
+        const newFilePath = join(this.directory, newFilename);
+        try {
+            // Check if old file exists
+            try {
+                await fs.access(oldFilePath);
+            }
+            catch {
+                // File doesn't exist, nothing to rotate
+                this.currentFileSize = 0;
+                return;
+            }
+            // Rename old file to rotated filename
+            await fs.rename(oldFilePath, newFilePath);
+            // Compress if enabled
+            if (this.compress && !newFilename.endsWith(".gz")) {
+                await this.compressFile(newFilePath);
+            }
+            // Reset current file size
+            this.currentFileSize = 0;
+        }
+        catch (error) {
+            // Only log error if it's not a "file not found" error (ENOENT)
+            // This can happen if file was deleted between access check and rename
+            const err = error;
+            if (err.code !== "ENOENT") {
+                console.error(`[FileTransport] Failed to rotate file:`, error);
+            }
+            // Reset file size on any error to prevent stuck state
+            this.currentFileSize = 0;
+        }
+    }
+    getRotatedFilename(filename) {
+        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const baseName = filename.replace(".log", "");
+        return `${baseName}-${timestamp}.log`;
+    }
+    async compressFile(filePath) {
+        try {
+            const gzipPath = `${filePath}.gz`;
+            const source = createReadStream(filePath);
+            const destination = createWriteStream(gzipPath);
+            const gzip = createGzip({ level: 6 }); // Default compression level
+            await pipeline(source, gzip, destination);
+            // Delete original file after successful compression
+            await fs.unlink(filePath);
+        }
+        catch (error) {
+            console.error(`[FileTransport] Failed to compress file:`, error);
+        }
+    }
+    startCleanupInterval() {
+        // Run cleanup every hour
+        this.cleanupInterval = setInterval(() => {
+            this.cleanupOldFiles().catch((error) => {
+                console.error(`[FileTransport] Cleanup failed:`, error);
+            });
+        }, 60 * 60 * 1000); // 1 hour
+        // Run initial cleanup
+        this.cleanupOldFiles().catch((error) => {
+            console.error(`[FileTransport] Initial cleanup failed:`, error);
+        });
+    }
+    async cleanupOldFiles() {
+        try {
+            const files = await fs.readdir(this.directory);
+            const now = Date.now();
+            const logFiles = [];
+            // Collect all log files with their metadata
+            for (const file of files) {
+                if (file.includes(this.filenamePattern.replace("%DATE%", ""))) {
+                    const filePath = join(this.directory, file);
+                    try {
+                        const stats = await fs.stat(filePath);
+                        logFiles.push({
+                            name: file,
+                            path: filePath,
+                            mtime: stats.mtimeMs,
+                        });
+                    }
+                    catch {
+                        // Skip files we can't stat
+                    }
+                }
+            }
+            // Sort by modification time (oldest first)
+            logFiles.sort((a, b) => a.mtime - b.mtime);
+            // Delete files that exceed maxAge
+            if (this.maxAge > 0) {
+                for (const file of logFiles) {
+                    const age = now - file.mtime;
+                    if (age > this.maxAge) {
+                        try {
+                            await fs.unlink(file.path);
+                        }
+                        catch (error) {
+                            console.error(`[FileTransport] Failed to delete old file:`, error);
+                        }
+                    }
+                }
+            }
+            // Delete files that exceed maxFiles (keep newest)
+            if (this.maxFiles > 0 && logFiles.length > this.maxFiles) {
+                const filesToDelete = logFiles.slice(0, logFiles.length - this.maxFiles);
+                for (const file of filesToDelete) {
+                    try {
+                        await fs.unlink(file.path);
+                    }
+                    catch (error) {
+                        console.error(`[FileTransport] Failed to delete excess file:`, error);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            console.error(`[FileTransport] Cleanup error:`, error);
+        }
+    }
+}

package/lib/esm/provider/logger/transports/http-server.js

@@ -0,0 +1,141 @@
+/**
+ * Log buffer for in-memory log storage.
+ */
+class LogBuffer {
+    buffer = [];
+    maxSize;
+    constructor(maxSize = 1000) {
+        this.maxSize = maxSize;
+    }
+    add(entry) {
+        this.buffer.push(entry);
+        if (this.buffer.length > this.maxSize) {
+            this.buffer.shift(); // Remove oldest entry
+        }
+    }
+    query(options) {
+        let results = [...this.buffer];
+        // Filter by level
+        if (options.level) {
+            results = results.filter((entry) => entry.level === options.level);
+        }
+        // Filter by context
+        if (options.context) {
+            results = results.filter((entry) => entry.context === options.context);
+        }
+        // Filter by time range
+        if (options.startTime) {
+            results = results.filter((entry) => entry.timestamp.getTime() >= options.startTime);
+        }
+        if (options.endTime) {
+            results = results.filter((entry) => entry.timestamp.getTime() <= options.endTime);
+        }
+        // Filter by search term
+        if (options.search) {
+            const searchLower = options.search.toLowerCase();
+            results = results.filter((entry) => entry.message.toLowerCase().includes(searchLower) ||
+                JSON.stringify(entry.data || {})
+                    .toLowerCase()
+                    .includes(searchLower));
+        }
+        // Sort (newest first by default)
+        results.sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
+        // Limit results
+        if (options.limit) {
+            results = results.slice(0, options.limit);
+        }
+        return results;
+    }
+    clear() {
+        this.buffer = [];
+    }
+    getStats() {
+        const levels = {};
+        const contexts = {};
+        for (const entry of this.buffer) {
+            levels[entry.level] = (levels[entry.level] || 0) + 1;
+            if (entry.context) {
+                contexts[entry.context] = (contexts[entry.context] || 0) + 1;
+            }
+        }
+        return {
+            total: this.buffer.length,
+            byLevel: levels,
+            byContext: contexts,
+            oldest: this.buffer.length > 0 ? this.buffer[0].timestamp.getTime() : null,
+            newest: this.buffer.length > 0
+                ? this.buffer[this.buffer.length - 1].timestamp.getTime()
+                : null,
+        };
+    }
+}
+/**
+ * HTTP server for log querying and streaming.
+ * This is a basic implementation that can be extended.
+ * @public API
+ */
+export class HttpLogServer {
+    buffer;
+    config;
+    server; // Express-like server (would need to be implemented)
+    constructor(config) {
+        this.config = {
+            port: config?.port ?? 3001,
+            maxLogs: config?.maxLogs ?? 1000,
+            enableWebSocket: config?.enableWebSocket ?? true,
+            enableRestApi: config?.enableRestApi ?? true,
+            apiPath: config?.apiPath ?? "/api/logs",
+        };
+        this.buffer = new LogBuffer(this.config.maxLogs);
+    }
+    /**
+     * Add a log entry to the buffer.
+     * @param entry - Log entry to add
+     */
+    addLog(entry) {
+        this.buffer.add(entry);
+    }
+    /**
+     * Query logs.
+     * @param options - Query options
+     * @returns Array of log entries
+     */
+    queryLogs(options) {
+        return this.buffer.query(options);
+    }
+    /**
+     * Get log statistics.
+     * @returns Log statistics
+     */
+    getStats() {
+        return this.buffer.getStats();
+    }
+    /**
+     * Clear all logs.
+     */
+    clearLogs() {
+        this.buffer.clear();
+    }
+    /**
+     * Start the HTTP server.
+     * Note: This is a placeholder - actual server implementation would require Express or similar.
+     */
+    async start() {
+        // Placeholder for server implementation
+        // In a real implementation, this would:
+        // 1. Set up Express server
+        // 2. Add REST API routes for querying logs
+        // 3. Set up WebSocket server for real-time streaming
+        // 4. Add endpoints for stats, export, etc.
+        console.log(`[HttpLogServer] Server would start on port ${this.config.port}`);
+        console.log(`[HttpLogServer] REST API would be available at ${this.config.apiPath}`);
+        console.log(`[HttpLogServer] WebSocket streaming would be available at ws://localhost:${this.config.port}/ws`);
+    }
+    /**
+     * Stop the HTTP server.
+     */
+    async stop() {
+        // Placeholder for server shutdown
+        console.log("[HttpLogServer] Server stopped");
+    }
+}

package/lib/esm/provider/logger/transports/http.transport.js

@@ -0,0 +1,157 @@
+import { LogLevel, shouldLog } from "../utils/log-levels.js";
+import { formatProd } from "../logger.formatter.js";
+/**
+ * HTTP transport for sending logs to remote endpoints with batching and retry.
+ * @public API
+ */
+export class HttpTransport {
+    name = "Http";
+    level;
+    enabled;
+    endpoint;
+    batchSize;
+    flushInterval;
+    maxRetries;
+    retryDelay;
+    headers;
+    method;
+    timeout;
+    buffer = [];
+    flushTimer = null;
+    isFlushing = false;
+    constructor(options) {
+        if (!options.endpoint) {
+            throw new Error("HttpTransport requires an endpoint URL");
+        }
+        this.endpoint = options.endpoint;
+        this.level = options?.level ?? LogLevel.INFO;
+        this.enabled = options?.enabled ?? true;
+        this.batchSize = options?.batchSize ?? 10;
+        this.flushInterval = options?.flushInterval ?? 5000;
+        this.maxRetries = options?.maxRetries ?? 3;
+        this.retryDelay = options?.retryDelay ?? 1000;
+        this.headers = {
+            "Content-Type": "application/json",
+            ...options?.headers,
+        };
+        this.method = options?.method ?? "POST";
+        this.timeout = options?.timeout ?? 10000;
+    }
+    /**
+     * Create an HTTP transport with default settings.
+     * @param endpoint - HTTP endpoint URL
+     * @param options - Additional options
+     * @returns HttpTransport instance
+     * @public API
+     */
+    static create(endpoint, options) {
+        return new HttpTransport({ endpoint, ...options });
+    }
+    /**
+     * Create an HTTP transport with batching enabled.
+     * @param endpoint - HTTP endpoint URL
+     * @param batchSize - Number of logs per batch
+     * @param options - Additional options
+     * @returns HttpTransport instance
+     * @public API
+     */
+    static withBatching(endpoint, batchSize = 10, options) {
+        return new HttpTransport({ endpoint, batchSize, ...options });
+    }
+    async log(entry) {
+        if (!this.enabled || !shouldLog(entry.level, this.level)) {
+            return;
+        }
+        this.buffer.push(entry);
+        // Flush if buffer reaches batch size
+        if (this.buffer.length >= this.batchSize) {
+            await this.flush();
+        }
+        else {
+            // Schedule flush if not already scheduled
+            this.scheduleFlush();
+        }
+    }
+    async flush() {
+        if (this.isFlushing || this.buffer.length === 0) {
+            return;
+        }
+        this.isFlushing = true;
+        this.cancelFlushTimer();
+        const entries = [...this.buffer];
+        this.buffer = [];
+        try {
+            await this.sendBatch(entries);
+        }
+        catch (error) {
+            // On failure, put entries back in buffer for retry
+            this.buffer.unshift(...entries);
+            console.error(`[HttpTransport] Failed to send logs:`, error);
+        }
+        finally {
+            this.isFlushing = false;
+        }
+    }
+    async close() {
+        this.cancelFlushTimer();
+        // Flush remaining logs
+        if (this.buffer.length > 0) {
+            await this.flush();
+        }
+    }
+    scheduleFlush() {
+        if (this.flushTimer) {
+            return; // Already scheduled
+        }
+        this.flushTimer = setTimeout(() => {
+            this.flush().catch((error) => {
+                console.error(`[HttpTransport] Scheduled flush failed:`, error);
+            });
+        }, this.flushInterval);
+    }
+    cancelFlushTimer() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+    async sendBatch(entries) {
+        const payload = entries.map((entry) => formatProd(entry));
+        const body = JSON.stringify({ logs: payload });
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+                const response = await fetch(this.endpoint, {
+                    method: this.method,
+                    headers: this.headers,
+                    body,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+                }
+                // Success - return
+                return;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Don't retry on abort (timeout)
+                if (error instanceof Error && error.name === "AbortError") {
+                    throw new Error(`Request timeout after ${this.timeout}ms`);
+                }
+                // Wait before retry (except on last attempt)
+                if (attempt < this.maxRetries) {
+                    await this.delay(this.retryDelay * (attempt + 1)); // Exponential backoff
+                }
+            }
+        }
+        // All retries failed
+        throw lastError || new Error("Failed to send logs after retries");
+    }
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/lib/esm/provider/logger/transports/index.js

@@ -0,0 +1,5 @@
+export * from "./transport.interface.js";
+export * from "./console.transport.js";
+export * from "./file.transport.js";
+export * from "./http.transport.js";
+export * from "./http-server.js";

package/lib/esm/provider/logger/transports/transport.interface.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/provider/logger/utils/index.js

@@ -0,0 +1,2 @@
+export * from "./log-levels.js";
+export * from "./log-entry.js";

package/lib/esm/provider/logger/utils/log-entry.js

@@ -0,0 +1,23 @@
+/**
+ * Create a log entry with defaults.
+ * @param level - Log level
+ * @param message - Log message
+ * @param options - Additional options
+ * @returns LogEntry
+ * @public API
+ */
+export function createLogEntry(level, message, options) {
+    return {
+        timestamp: new Date(),
+        level,
+        message,
+        context: options?.context,
+        data: options?.data,
+        error: options?.error,
+        trace: options?.trace,
+        performance: options?.performance,
+        flow: options?.flow,
+        pid: options?.pid ?? process.pid,
+        metadata: options?.metadata,
+    };
+}