@expressots/core 3.0.0-beta.4 → 4.0.0-preview.1

package/lib/esm/provider/logger/logger.query.js

@@ -0,0 +1,529 @@
+import { LogLevel } from "./utils/log-levels.js";
+/**
+ * Log query builder for chainable queries.
+ * @public API
+ */
+export class LogQuery {
+    entries;
+    results;
+    constructor(entries) {
+        this.entries = entries;
+        this.results = entries;
+    }
+    /**
+     * Filter by log level(s).
+     * @param level - Single level or array of levels
+     * @returns Query builder instance
+     * @public API
+     */
+    level(level) {
+        const levels = Array.isArray(level) ? level : [level];
+        this.results = this.results.filter((entry) => levels.includes(entry.level));
+        return this;
+    }
+    /**
+     * Filter by context (exact match or regex).
+     * @param context - Context string or regex pattern
+     * @returns Query builder instance
+     * @public API
+     */
+    context(context) {
+        if (context instanceof RegExp) {
+            this.results = this.results.filter((entry) => entry.context && context.test(entry.context));
+        }
+        else {
+            this.results = this.results.filter((entry) => entry.context === context);
+        }
+        return this;
+    }
+    /**
+     * Filter by time range.
+     * @param start - Start time (timestamp or Date)
+     * @param end - End time (timestamp or Date)
+     * @returns Query builder instance
+     * @public API
+     */
+    timeRange(start, end) {
+        if (start !== undefined) {
+            const startTime = start instanceof Date ? start.getTime() : start;
+            this.results = this.results.filter((entry) => entry.timestamp.getTime() >= startTime);
+        }
+        if (end !== undefined) {
+            const endTime = end instanceof Date ? end.getTime() : end;
+            // End time is exclusive (<) when both start and end are provided, inclusive (<=) when only end is provided
+            if (start !== undefined) {
+                this.results = this.results.filter((entry) => entry.timestamp.getTime() < endTime);
+            }
+            else {
+                this.results = this.results.filter((entry) => entry.timestamp.getTime() <= endTime);
+            }
+        }
+        return this;
+    }
+    /**
+     * Search in message and data fields.
+     * @param term - Search term (case-insensitive)
+     * @returns Query builder instance
+     * @public API
+     */
+    search(term) {
+        const searchLower = term.toLowerCase();
+        this.results = this.results.filter((entry) => entry.message.toLowerCase().includes(searchLower) ||
+            (entry.data &&
+                JSON.stringify(entry.data).toLowerCase().includes(searchLower)) ||
+            (entry.context && entry.context.toLowerCase().includes(searchLower)));
+        return this;
+    }
+    /**
+     * Filter by regex pattern on message.
+     * @param pattern - Regex pattern (string or RegExp)
+     * @returns Query builder instance
+     * @public API
+     */
+    messageRegex(pattern) {
+        const regex = typeof pattern === "string" ? new RegExp(pattern, "i") : pattern;
+        this.results = this.results.filter((entry) => regex.test(entry.message));
+        return this;
+    }
+    /**
+     * Limit the number of results.
+     * @param limit - Maximum number of results
+     * @returns Query builder instance
+     * @public API
+     */
+    limit(limit) {
+        this.results = this.results.slice(0, limit);
+        return this;
+    }
+    /**
+     * Sort results by timestamp.
+     * @param order - Sort order: 'asc' (oldest first) or 'desc' (newest first)
+     * @returns Query builder instance
+     * @public API
+     */
+    sort(order = "desc") {
+        this.results.sort((a, b) => {
+            const diff = a.timestamp.getTime() - b.timestamp.getTime();
+            return order === "asc" ? diff : -diff;
+        });
+        return this;
+    }
+    /**
+     * Execute the query and return results.
+     * @returns Array of log entries matching the query
+     * @public API
+     */
+    execute() {
+        return [...this.results];
+    }
+    /**
+     * Get the count of matching results.
+     * @returns Number of matching entries
+     * @public API
+     */
+    count() {
+        return this.results.length;
+    }
+    /**
+     * Get statistics about the query results.
+     * @returns Query statistics
+     * @public API
+     */
+    stats() {
+        const levels = {};
+        const contexts = {};
+        for (const entry of this.results) {
+            const levelName = LogLevel[entry.level] || String(entry.level);
+            levels[levelName] = (levels[levelName] || 0) + 1;
+            if (entry.context) {
+                contexts[entry.context] = (contexts[entry.context] || 0) + 1;
+            }
+        }
+        return {
+            total: this.results.length,
+            byLevel: levels,
+            byContext: contexts,
+            oldest: this.results.length > 0 ? this.results[0].timestamp.getTime() : null,
+            newest: this.results.length > 0
+                ? this.results[this.results.length - 1].timestamp.getTime()
+                : null,
+        };
+    }
+}
+/**
+ * Circular buffer for storing log entries in memory.
+ * Thread-safe for single-threaded Node.js (no concurrent access needed).
+ * @public API
+ */
+export class LogBuffer {
+    buffer = [];
+    maxSize;
+    writeIndex = 0;
+    constructor(maxSize = 1000) {
+        this.maxSize = maxSize;
+    }
+    /**
+     * Add a log entry to the buffer.
+     * Uses circular buffer logic for efficient memory usage.
+     * @param entry - Log entry to add
+     */
+    add(entry) {
+        if (this.buffer.length < this.maxSize) {
+            // Buffer not full yet, just append
+            this.buffer.push(entry);
+        }
+        else {
+            // Buffer is full, overwrite oldest entry (circular)
+            this.buffer[this.writeIndex] = entry;
+            this.writeIndex = (this.writeIndex + 1) % this.maxSize;
+        }
+    }
+    /**
+     * Query logs with options.
+     * @param options - Query options
+     * @returns Array of matching log entries
+     */
+    query(options = {}) {
+        const query = new LogQuery(this.getAll());
+        // Apply filters
+        if (options.level) {
+            query.level(options.level);
+        }
+        if (options.context) {
+            query.context(options.context);
+        }
+        if (options.startTime || options.endTime) {
+            query.timeRange(options.startTime, options.endTime);
+        }
+        if (options.search) {
+            query.search(options.search);
+        }
+        if (options.messageRegex) {
+            query.messageRegex(options.messageRegex);
+        }
+        // Apply sorting
+        query.sort(options.sort || "desc");
+        // Apply limit
+        if (options.limit) {
+            query.limit(options.limit);
+        }
+        return query.execute();
+    }
+    /**
+     * Create a chainable query builder.
+     * @returns LogQuery instance
+     */
+    createQuery() {
+        return new LogQuery(this.getAll());
+    }
+    /**
+     * Get all logs in the buffer.
+     * @returns Array of all log entries in chronological order (oldest first)
+     */
+    getAll() {
+        if (this.buffer.length < this.maxSize) {
+            // Buffer not full yet, already in correct order
+            return [...this.buffer];
+        }
+        // Buffer is full, need to reorder circular buffer
+        // writeIndex points to the next position to write (oldest entry)
+        const ordered = [];
+        for (let i = 0; i < this.maxSize; i++) {
+            const index = (this.writeIndex + i) % this.maxSize;
+            ordered.push(this.buffer[index]);
+        }
+        return ordered;
+    }
+    /**
+     * Clear all logs from the buffer.
+     */
+    clear() {
+        this.buffer = [];
+        this.writeIndex = 0;
+    }
+    /**
+     * Get statistics about the buffer.
+     * @returns Buffer statistics
+     */
+    getStats() {
+        const allEntries = this.getAll();
+        const levels = {};
+        const contexts = {};
+        for (const entry of allEntries) {
+            const levelName = LogLevel[entry.level] || String(entry.level);
+            levels[levelName] = (levels[levelName] || 0) + 1;
+            if (entry.context) {
+                contexts[entry.context] = (contexts[entry.context] || 0) + 1;
+            }
+        }
+        return {
+            total: allEntries.length,
+            byLevel: levels,
+            byContext: contexts,
+            oldest: allEntries.length > 0 ? allEntries[0].timestamp.getTime() : null,
+            newest: allEntries.length > 0
+                ? allEntries[allEntries.length - 1].timestamp.getTime()
+                : null,
+        };
+    }
+    /**
+     * Get the current buffer size.
+     * @returns Number of entries in buffer
+     */
+    size() {
+        return this.buffer.length;
+    }
+}
+/**
+ * Log query manager for managing in-memory log buffer and queries.
+ * @public API
+ */
+export class LogQueryManager {
+    buffer = null;
+    config;
+    constructor(config) {
+        const isDevelopment = process.env.NODE_ENV !== "production";
+        this.config = {
+            enabled: config?.enabled ?? isDevelopment,
+            bufferSize: config?.bufferSize ?? 1000,
+            enableExport: config?.enableExport ?? true,
+        };
+        if (this.config.enabled) {
+            this.buffer = new LogBuffer(this.config.bufferSize);
+        }
+    }
+    /**
+     * Add a log entry to the buffer (if enabled).
+     * @param entry - Log entry to add
+     */
+    addEntry(entry) {
+        if (this.buffer && this.config.enabled) {
+            this.buffer.add(entry);
+        }
+    }
+    /**
+     * Query logs with options.
+     * @param options - Query options
+     * @returns Array of matching log entries
+     */
+    query(options = {}) {
+        if (!this.buffer) {
+            return [];
+        }
+        return this.buffer.query(options);
+    }
+    /**
+     * Create a chainable query builder.
+     * @returns LogQuery instance
+     */
+    createQuery() {
+        if (!this.buffer) {
+            return new LogQuery([]);
+        }
+        return this.buffer.createQuery();
+    }
+    /**
+     * Get all logs in the buffer.
+     * @returns Array of all log entries
+     */
+    getAll() {
+        if (!this.buffer) {
+            return [];
+        }
+        return this.buffer.getAll();
+    }
+    /**
+     * Clear all logs from the buffer.
+     */
+    clear() {
+        if (this.buffer) {
+            this.buffer.clear();
+        }
+    }
+    /**
+     * Get statistics about the buffer.
+     * @returns Buffer statistics
+     */
+    getStats() {
+        if (!this.buffer) {
+            return {
+                total: 0,
+                byLevel: {},
+                byContext: {},
+                oldest: null,
+                newest: null,
+            };
+        }
+        return this.buffer.getStats();
+    }
+    /**
+     * Check if query features are enabled.
+     * @returns True if enabled
+     */
+    isEnabled() {
+        return this.config.enabled === true && this.buffer !== null;
+    }
+    /**
+     * Configure the query manager.
+     * @param config - Partial configuration
+     */
+    configure(config) {
+        this.config = { ...this.config, ...config };
+        if (this.config.enabled && !this.buffer) {
+            this.buffer = new LogBuffer(this.config.bufferSize);
+        }
+        else if (!this.config.enabled && this.buffer) {
+            this.buffer.clear();
+            this.buffer = null;
+        }
+        else if (this.buffer && config.bufferSize) {
+            // Resize buffer (would need to implement resize logic)
+            // For now, just update maxSize for future entries
+        }
+    }
+}
+/**
+ * Format a log entry as markdown.
+ * @param entry - Log entry
+ * @returns Markdown string
+ */
+function formatLogEntryAsMarkdown(entry) {
+    const levelName = LogLevel[entry.level] || String(entry.level);
+    const timestamp = entry.timestamp.toISOString();
+    const context = entry.context ? `[${entry.context}]` : "";
+    let markdown = `### ${levelName} ${context}\n\n`;
+    markdown += `**Time**: ${timestamp}\n\n`;
+    markdown += `**Message**: ${entry.message}\n\n`;
+    if (entry.data) {
+        markdown += `**Data**:\n\`\`\`json\n${JSON.stringify(entry.data, null, 2)}\n\`\`\`\n\n`;
+    }
+    if (entry.error) {
+        markdown += `**Error**:\n\`\`\`\n`;
+        if (entry.error instanceof Error) {
+            markdown += `${entry.error.name}: ${entry.error.message}\n`;
+            if (entry.error.stack) {
+                markdown += entry.error.stack;
+            }
+        }
+        else {
+            markdown += String(entry.error);
+        }
+        markdown += `\n\`\`\`\n\n`;
+    }
+    if (entry.trace) {
+        markdown += `**Trace**:\n\`\`\`json\n${JSON.stringify(entry.trace, null, 2)}\n\`\`\`\n\n`;
+    }
+    if (entry.performance) {
+        markdown += `**Performance**:\n`;
+        if (entry.performance.duration) {
+            markdown += `- Duration: ${entry.performance.duration}ms\n`;
+        }
+        if (entry.performance.memoryDelta) {
+            markdown += `- Memory Delta: ${(entry.performance.memoryDelta / 1024).toFixed(2)} KB\n`;
+        }
+        if (entry.performance.cpuUsage) {
+            markdown += `- CPU Usage: ${entry.performance.cpuUsage.toFixed(2)}%\n`;
+        }
+        markdown += `\n`;
+    }
+    markdown += `---\n\n`;
+    return markdown;
+}
+/**
+ * Export logs to markdown format.
+ * @param entries - Log entries to export
+ * @param options - Export options
+ * @returns Markdown string
+ * @public API
+ */
+export function exportToMarkdown(entries, options = {}) {
+    const { title = "Log Export", includeStats = true, groupBy = "none", } = options;
+    let markdown = `# ${title}\n\n`;
+    markdown += `**Generated**: ${new Date().toISOString()}\n\n`;
+    // Calculate statistics
+    const stats = {
+        total: entries.length,
+        byLevel: {},
+        byContext: {},
+        oldest: entries.length > 0 ? entries[0].timestamp.getTime() : null,
+        newest: entries.length > 0
+            ? entries[entries.length - 1].timestamp.getTime()
+            : null,
+    };
+    for (const entry of entries) {
+        const levelName = LogLevel[entry.level] || String(entry.level);
+        stats.byLevel[levelName] = (stats.byLevel[levelName] || 0) + 1;
+        if (entry.context) {
+            stats.byContext[entry.context] =
+                (stats.byContext[entry.context] || 0) + 1;
+        }
+    }
+    // Include statistics section
+    if (includeStats) {
+        markdown += `## Statistics\n\n`;
+        markdown += `- **Total Logs**: ${stats.total}\n`;
+        markdown += `- **Oldest Entry**: ${stats.oldest ? new Date(stats.oldest).toISOString() : "N/A"}\n`;
+        markdown += `- **Newest Entry**: ${stats.newest ? new Date(stats.newest).toISOString() : "N/A"}\n\n`;
+        if (Object.keys(stats.byLevel).length > 0) {
+            markdown += `### By Level\n\n`;
+            for (const [level, count] of Object.entries(stats.byLevel)) {
+                markdown += `- **${level}**: ${count}\n`;
+            }
+            markdown += `\n`;
+        }
+        if (Object.keys(stats.byContext).length > 0) {
+            markdown += `### By Context\n\n`;
+            for (const [context, count] of Object.entries(stats.byContext)) {
+                markdown += `- **${context}**: ${count}\n`;
+            }
+            markdown += `\n`;
+        }
+    }
+    // Group entries if requested
+    let groupedEntries = [];
+    if (groupBy === "level") {
+        const groups = {};
+        for (const entry of entries) {
+            const levelName = LogLevel[entry.level] || String(entry.level);
+            if (!groups[levelName]) {
+                groups[levelName] = [];
+            }
+            groups[levelName].push(entry);
+        }
+        groupedEntries = Object.entries(groups).map(([key, entries]) => ({
+            key,
+            entries,
+        }));
+    }
+    else if (groupBy === "context") {
+        const groups = {};
+        for (const entry of entries) {
+            const context = entry.context || "Unknown";
+            if (!groups[context]) {
+                groups[context] = [];
+            }
+            groups[context].push(entry);
+        }
+        groupedEntries = Object.entries(groups).map(([key, entries]) => ({
+            key,
+            entries,
+        }));
+    }
+    else {
+        // When groupBy is "none", use entries directly without grouping
+        groupedEntries = [{ key: "", entries }];
+    }
+    // Export entries
+    markdown += `## Log Entries\n\n`;
+    for (const group of groupedEntries) {
+        // Only add group header if groupBy is explicitly set to "level" or "context"
+        // When groupBy is "none", skip adding any group headers
+        if (groupBy === "level" || groupBy === "context") {
+            markdown += `## ${group.key}\n\n`;
+        }
+        for (const entry of group.entries) {
+            markdown += formatLogEntryAsMarkdown(entry);
+        }
+    }
+    return markdown;
+}