@peers-app/peers-sdk 0.7.17 → 0.7.19

package/dist/logging/console-logger.js

@@ -1,9 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
 exports.setupConsoleProxy = setupConsoleProxy;
 exports.restoreConsole = restoreConsole;
+exports.extractCoreMessage = extractCoreMessage;
+exports.markLoggingInitialized = markLoggingInitialized;
+exports.resetLoggingState = resetLoggingState;
 const utils_1 = require("../utils");
 const console_logs_table_1 = require("./console-logs.table");
+const startupDelayForWritingLogsToDB = Date.now() + 2_000;
 // Store original console methods
 const originalConsole = {
     debug: console.debug,
@@ -15,6 +20,19 @@ const originalConsole = {
 let isProxySetup = false;
 let currentProcessName = 'unknown';
 let currentProcessInstanceId = '';
+// Guard against infinite recursion during log processing (single process)
+let isWritingLog = false;
+let recursionAttempts = 0;
+const MAX_RECURSION_ATTEMPTS = 3;
+// Guard against cross-process infinite loops
+// Track recent log signatures (hash of message + level + source)
+const recentLogSignatures = new Map();
+const LOG_SIGNATURE_WINDOW_MS = 5000; // 5 second window
+const MAX_IDENTICAL_LOGS_IN_WINDOW = 10; // Max same log in window
+// Track initialization state
+let isInitialized = false;
+const pendingLogs = [];
+const MAX_PENDING_LOGS = 1000; // Prevent memory buildup if initialization never happens
 /**
  * Setup console proxy to capture all console output and write to ConsoleLogs table.
  * Also subscribes to dataChanged events to output logs from other process instances.
@@ -96,6 +114,26 @@ function restoreConsole() {
  * Write a log entry to the ConsoleLogs table
  */
 async function writeLogToDatabase(level, args) {
+    const timestamp = (0, utils_1.getTimestamp)();
+    if (timestamp < startupDelayForWritingLogsToDB) {
+        await (0, utils_1.sleep)(startupDelayForWritingLogsToDB - timestamp);
+    }
+    // Guard against infinite recursion (same process)
+    if (isWritingLog) {
+        recursionAttempts++;
+        if (recursionAttempts >= MAX_RECURSION_ATTEMPTS) {
+            // Break the loop by using original console
+            originalConsole.error(`[console-logger] Infinite loop detected after ${recursionAttempts} attempts, dropping log write`, { level, args });
+            // Reset counter after a delay to allow recovery
+            setTimeout(() => {
+                recursionAttempts = 0;
+            }, 1000);
+            return;
+        }
+        // Allow a few attempts in case of legitimate nested logging
+        return;
+    }
+    isWritingLog = true;
     try {
         // Format message from arguments
         const message = formatLogMessage(args);
@@ -105,9 +143,19 @@ async function writeLogToDatabase(level, args) {
         const stackTrace = level === 'error' ? getStackTrace() : undefined;
         // Extract source from stack trace
         const source = extractSource(stackTrace);
+        // Guard against cross-process infinite loops
+        // Extract core message to detect loops even when processes add prefixes
+        const coreMessage = extractCoreMessage(message);
+        // Create signature from level + source + core message (not the full message)
+        const signature = `${level}:${source || 'unknown'}:${coreMessage.substring(0, 100)}`;
+        if (!checkLogSignature(signature)) {
+            // Too many identical logs in window, likely an infinite loop
+            originalConsole.warn(`[console-logger] Cross-process infinite loop detected for log: ${signature.substring(0, 80)}...`);
+            return;
+        }
         const logRecord = {
             logId: (0, utils_1.newid)(),
-            timestamp: (0, utils_1.getTimestamp)(),
+            timestamp,
             level,
             process: currentProcessName,
             processInstanceId: currentProcessInstanceId,
@@ -120,9 +168,63 @@ async function writeLogToDatabase(level, args) {
         await consoleLogsTable.insert(logRecord);
     }
     catch (err) {
+        originalConsole.error(`error while trying to write console log`, err);
         // Silently fail if table not available (e.g., during initialization)
         // Don't use console here to avoid infinite recursion
     }
+    finally {
+        isWritingLog = false;
+        recursionAttempts = 0;
+    }
+}
+/**
+ * Extract core message by removing common prefixes that might be added by different processes
+ * This helps detect cross-process loops where each process adds its own prefix
+ * @internal Exported for testing
+ */
+function extractCoreMessage(message) {
+    let core = message;
+    // Remove common process/context prefixes like [main], [renderer], [process-name]
+    // Keep removing until no more matches found
+    let previousCore = '';
+    while (core !== previousCore) {
+        previousCore = core;
+        // Remove [xxx] prefixes
+        core = core.replace(/^\[[^\]]+\]\s*/g, '');
+        // Remove common timestamp patterns
+        core = core.replace(/^\d{4}-\d{2}-\d{2}[T\s]\d{2}:\d{2}:\d{2}[^\s]*\s*/g, '');
+        // Remove "Error: " prefix that might be added
+        core = core.replace(/^Error:\s*/i, '');
+    }
+    return core.trim();
+}
+/**
+ * Check if a log signature is within acceptable frequency limits
+ * Returns false if this log should be dropped due to suspected infinite loop
+ */
+function checkLogSignature(signature) {
+    const now = Date.now();
+    // Clean up old entries outside the window
+    for (const [key, value] of recentLogSignatures.entries()) {
+        if (now - value.firstSeen > LOG_SIGNATURE_WINDOW_MS) {
+            recentLogSignatures.delete(key);
+        }
+    }
+    // Check current signature
+    const existing = recentLogSignatures.get(signature);
+    if (!existing) {
+        // First time seeing this log
+        recentLogSignatures.set(signature, { count: 1, firstSeen: now });
+        return true;
+    }
+    // Within window, increment count
+    existing.count++;
+    if (existing.count > MAX_IDENTICAL_LOGS_IN_WINDOW) {
+        // Too many identical logs, likely infinite loop
+        // Keep the entry to continue blocking (will be cleaned up after window expires)
+        return false;
+    }
+    return true;
 }
 /**
  * Format log arguments into a single message string
@@ -204,3 +306,172 @@ function extractSource(stackTrace) {
     }
     return undefined;
 }
+/**
+ * Mark the logging system as initialized and flush any pending logs
+ */
+function markLoggingInitialized() {
+    isInitialized = true;
+    // Flush pending logs sequentially with small delays to avoid recursion guard
+    if (pendingLogs.length > 0) {
+        originalConsole.log(`[console-logger] Flushing ${pendingLogs.length} pending logs...`);
+        const logsToFlush = [...pendingLogs]; // Copy array
+        pendingLogs.length = 0; // Clear the original array
+        // Flush logs with small delays between them
+        let delay = 0;
+        for (const { level, source, args } of logsToFlush) {
+            setTimeout(() => {
+                writeLogToDatabaseWithSource(level, source, args).catch((err) => {
+                    originalConsole.error('[console-logger] Failed to flush pending log:', err);
+                });
+            }, delay);
+            delay += 10; // 10ms between each log
+        }
+    }
+}
+/**
+ * Reset logging initialization state (primarily for testing)
+ * @internal
+ */
+function resetLoggingState() {
+    isInitialized = false;
+    pendingLogs.length = 0;
+}
+/**
+ * Write a log entry to the ConsoleLogs table with a specific source
+ */
+async function writeLogToDatabaseWithSource(level, source, args) {
+    const timestamp = (0, utils_1.getTimestamp)();
+    if (timestamp < startupDelayForWritingLogsToDB) {
+        await (0, utils_1.sleep)(startupDelayForWritingLogsToDB - timestamp);
+    }
+    // Guard against infinite recursion (same process)
+    if (isWritingLog) {
+        recursionAttempts++;
+        if (recursionAttempts >= MAX_RECURSION_ATTEMPTS) {
+            originalConsole.error(`[console-logger] Infinite loop detected after ${recursionAttempts} attempts, dropping log write`, { level, source, args });
+            setTimeout(() => {
+                recursionAttempts = 0;
+            }, 1000);
+            return;
+        }
+        return;
+    }
+    isWritingLog = true;
+    try {
+        // Format message from arguments
+        const message = formatLogMessage(args);
+        // Extract context objects from arguments
+        const context = extractContext(args);
+        // Get stack trace for errors
+        const stackTrace = level === 'error' ? getStackTrace() : undefined;
+        // Guard against cross-process infinite loops
+        const coreMessage = extractCoreMessage(message);
+        const signature = `${level}:${source}:${coreMessage.substring(0, 100)}`;
+        if (!checkLogSignature(signature)) {
+            originalConsole.warn(`[console-logger] Cross-process infinite loop detected for log: ${signature.substring(0, 80)}...`);
+            return;
+        }
+        const logRecord = {
+            logId: (0, utils_1.newid)(),
+            timestamp,
+            level,
+            process: currentProcessName,
+            processInstanceId: currentProcessInstanceId,
+            source,
+            message,
+            context,
+            stackTrace,
+        };
+        const consoleLogsTable = await (0, console_logs_table_1.ConsoleLogs)();
+        await consoleLogsTable.insert(logRecord);
+    }
+    catch (err) {
+        // Silently fail if table not available
+    }
+    finally {
+        isWritingLog = false;
+        recursionAttempts = 0;
+    }
+}
+/**
+ * Logger class for creating source-specific loggers
+ *
+ * Usage:
+ * ```typescript
+ * const logger = new Logger('MyModule');
+ * logger.log('Something happened');
+ * logger.error('An error occurred');
+ * ```
+ */
+class Logger {
+    source;
+    constructor(source) {
+        // If no source provided, try to extract from caller's location
+        if (!source) {
+            const stack = new Error().stack;
+            source = extractSource(stack) || 'unknown';
+        }
+        this.source = source;
+        // ConsoleLogs().then(() => {
+        //   markLoggingInitialized();
+        // })
+    }
+    /**
+     * Log a debug message
+     */
+    debug(...args) {
+        originalConsole.debug(...args);
+        this.writeLog('debug', args);
+    }
+    /**
+     * Log an info message
+     */
+    info(...args) {
+        originalConsole.info(...args);
+        this.writeLog('info', args);
+    }
+    /**
+     * Log a general message
+     */
+    log(...args) {
+        originalConsole.log(...args);
+        this.writeLog('log', args);
+    }
+    /**
+     * Log a warning message
+     */
+    warn(...args) {
+        originalConsole.warn(...args);
+        this.writeLog('warn', args);
+    }
+    /**
+     * Log an error message
+     */
+    error(...args) {
+        originalConsole.error(...args);
+        this.writeLog('error', args);
+    }
+    /**
+     * Internal method to write log to database
+     */
+    writeLog(level, args) {
+        if (!isInitialized) {
+            // Queue the log until system is initialized
+            if (pendingLogs.length < MAX_PENDING_LOGS) {
+                pendingLogs.push({ level, source: this.source, args });
+            }
+            else {
+                // Drop logs if queue is full to prevent memory issues
+                if (pendingLogs.length === MAX_PENDING_LOGS) {
+                    originalConsole.warn('[console-logger] Pending log queue is full, dropping new logs until initialization');
+                }
+            }
+            return;
+        }
+        // System is initialized, write directly
+        writeLogToDatabaseWithSource(level, this.source, args).catch((err) => {
+            originalConsole.error('[console-logger] Failed to write log:', err);
+        });
+    }
+}
+exports.Logger = Logger;

package/dist/logging/console-logger.test.d.ts

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

package/dist/logging/console-logger.test.js

@@ -0,0 +1,300 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const console_logger_1 = require("./console-logger");
+// Mock the ConsoleLogs table
+jest.mock('./console-logs.table', () => {
+    const mockTable = {
+        insert: jest.fn().mockResolvedValue(undefined),
+        dataChanged: {
+            subscribe: jest.fn(),
+        },
+    };
+    return {
+        ConsoleLogs: jest.fn().mockResolvedValue(mockTable),
+    };
+});
+// Mock utils
+jest.mock('../utils', () => ({
+    newid: () => 'test-id-123',
+    getTimestamp: () => '2024-01-01T00:00:00.000Z',
+}));
+describe('console-logger', () => {
+    let originalConsole;
+    describe('extractCoreMessage', () => {
+        it('should extract core message from messages with [prefix] tags', () => {
+            expect((0, console_logger_1.extractCoreMessage)('[main] Error message')).toBe('Error message');
+            expect((0, console_logger_1.extractCoreMessage)('[renderer] [main] Error message')).toBe('Error message');
+            expect((0, console_logger_1.extractCoreMessage)('[process-1] [process-2] [process-3] Error message')).toBe('Error message');
+        });
+        it('should remove Error: prefix', () => {
+            expect((0, console_logger_1.extractCoreMessage)('Error: Something went wrong')).toBe('Something went wrong');
+            expect((0, console_logger_1.extractCoreMessage)('[main] Error: Something went wrong')).toBe('Something went wrong');
+        });
+        it('should remove timestamp patterns', () => {
+            expect((0, console_logger_1.extractCoreMessage)('2024-01-01T12:00:00.000Z Error message')).toBe('Error message');
+            expect((0, console_logger_1.extractCoreMessage)('2024-01-01 12:00:00 Error message')).toBe('Error message');
+        });
+        it('should handle combinations of prefixes', () => {
+            expect((0, console_logger_1.extractCoreMessage)('[renderer] 2024-01-01T12:00:00.000Z Error: Failed to write log')).toBe('Failed to write log');
+            expect((0, console_logger_1.extractCoreMessage)('[main] [renderer] Error: Failed to write log')).toBe('Failed to write log');
+        });
+        it('should return the same message if no prefixes found', () => {
+            expect((0, console_logger_1.extractCoreMessage)('Plain error message')).toBe('Plain error message');
+        });
+        it('should handle empty or whitespace messages', () => {
+            expect((0, console_logger_1.extractCoreMessage)('')).toBe('');
+            expect((0, console_logger_1.extractCoreMessage)('   ')).toBe('');
+            expect((0, console_logger_1.extractCoreMessage)('[main]')).toBe('');
+        });
+    });
+    beforeAll(() => {
+        // Save original console methods
+        originalConsole = {
+            debug: console.debug,
+            info: console.info,
+            log: console.log,
+            warn: console.warn,
+            error: console.error,
+        };
+    });
+    beforeEach(() => {
+        // Clear all mocks
+        jest.clearAllMocks();
+        // Restore console before each test
+        (0, console_logger_1.restoreConsole)();
+    });
+    afterAll(() => {
+        // Restore original console methods
+        console.debug = originalConsole.debug;
+        console.info = originalConsole.info;
+        console.log = originalConsole.log;
+        console.warn = originalConsole.warn;
+        console.error = originalConsole.error;
+    });
+    describe('Single-process infinite loop detection', () => {
+        it('should detect infinite loop when logging from within log handler', async () => {
+            const { ConsoleLogs } = require('./console-logs.table');
+            const mockTable = await ConsoleLogs();
+            // Setup mock to throw error that triggers another log
+            let callCount = 0;
+            mockTable.insert.mockImplementation(() => {
+                callCount++;
+                if (callCount < 10) {
+                    // This would trigger another log attempt
+                    throw new Error('Database error');
+                }
+                return Promise.resolve();
+            });
+            await (0, console_logger_1.setupConsoleProxy)('test-process');
+            // This should trigger the loop
+            console.error('Initial error');
+            // Wait for async operations
+            await new Promise(resolve => setTimeout(resolve, 100));
+            // Should have called insert but stopped early due to recursion guard
+            expect(mockTable.insert).toHaveBeenCalled();
+            // The recursion guard should stop it after just 1 attempt
+            // (because isWritingLog prevents re-entry)
+            expect(callCount).toBeLessThanOrEqual(2); // Setup log + 1 error attempt
+        });
+    });
+    describe('Cross-process infinite loop detection', () => {
+        it('should detect when same log is written too many times in window', async () => {
+            const { ConsoleLogs } = require('./console-logs.table');
+            const mockTable = await ConsoleLogs();
+            await (0, console_logger_1.setupConsoleProxy)('test-process');
+            // Log the same message many times quickly (simulating cross-process loop)
+            for (let i = 0; i < 15; i++) {
+                console.error('Same error message');
+                // Small delay to ensure they're processed
+                await new Promise(resolve => setTimeout(resolve, 10));
+            }
+            // Wait for async operations
+            await new Promise(resolve => setTimeout(resolve, 100));
+            // Should have stopped writing after threshold (10)
+            // Plus 1 for the setup log
+            expect(mockTable.insert.mock.calls.length).toBeLessThan(15);
+            expect(mockTable.insert.mock.calls.length).toBeGreaterThan(0);
+        });
+        it('should NOT detect loop for different messages', async () => {
+            const { ConsoleLogs } = require('./console-logs.table');
+            const mockTable = await ConsoleLogs();
+            await (0, console_logger_1.setupConsoleProxy)('test-process');
+            // Clear setup log
+            mockTable.insert.mockClear();
+            // Log different messages
+            for (let i = 0; i < 15; i++) {
+                console.error(`Different error message ${i}`);
+                await new Promise(resolve => setTimeout(resolve, 10));
+            }
+            // Wait for async operations
+            await new Promise(resolve => setTimeout(resolve, 100));
+            // Should have written most/all messages (allow for timing variance)
+            expect(mockTable.insert.mock.calls.length).toBeGreaterThanOrEqual(14);
+            expect(mockTable.insert.mock.calls.length).toBeLessThanOrEqual(15);
+        });
+        it('should detect loop even with modified messages (prefix added)', async () => {
+            const { ConsoleLogs } = require('./console-logs.table');
+            const mockTable = await ConsoleLogs();
+            await (0, console_logger_1.setupConsoleProxy)('test-process');
+            // Simulate cross-process loop where each process adds a prefix
+            // This represents Process A logging "Error X"
+            // Process B seeing it and logging "[main] Error X"
+            // Process A seeing that and logging "[renderer] [main] Error X"
+            const baseMessage = 'Failed to write log to database';
+            const messages = [
+                baseMessage,
+                `[main] ${baseMessage}`,
+                `[renderer] [main] ${baseMessage}`,
+                `[main] [renderer] [main] ${baseMessage}`,
+                `[renderer] [main] [renderer] [main] ${baseMessage}`,
+            ];
+            // Log these messages in sequence, simulating the loop
+            // Need enough to trigger the threshold (MAX_IDENTICAL_LOGS_IN_WINDOW = 10)
+            for (let cycle = 0; cycle < 3; cycle++) {
+                for (const msg of messages) {
+                    console.error(msg);
+                    await new Promise(resolve => setTimeout(resolve, 10));
+                }
+            }
+            // Wait for async operations
+            await new Promise(resolve => setTimeout(resolve, 100));
+            // Should detect this as a loop even though messages have different prefixes
+            // because extractCoreMessage normalizes them all to the same core message
+            // We logged 15 messages (5 variants x 3 cycles), but they all have the same core
+            // So after 10, it should start blocking
+            const insertCount = mockTable.insert.mock.calls.length;
+            // Should be: 1 (setup) + 10 (threshold) = 11, might be a bit more due to timing
+            expect(insertCount).toBeGreaterThan(1); // At least setup + some logs
+            expect(insertCount).toBeLessThan(17); // Definitely less than all 15 + setup
+        });
+    });
+    describe('Loop detection recovery', () => {
+        it('should allow logging again after window expires', async () => {
+            const { ConsoleLogs } = require('./console-logs.table');
+            const mockTable = await ConsoleLogs();
+            await (0, console_logger_1.setupConsoleProxy)('test-process');
+            // Trigger loop detection
+            for (let i = 0; i < 12; i++) {
+                console.error('Same error');
+                await new Promise(resolve => setTimeout(resolve, 10));
+            }
+            await new Promise(resolve => setTimeout(resolve, 100));
+            const firstBatchCount = mockTable.insert.mock.calls.length;
+            // Wait for window to expire (5 seconds in real code, but we can't easily test that)
+            // Just verify the blocking is in place
+            console.error('Same error');
+            await new Promise(resolve => setTimeout(resolve, 100));
+            // Should still be blocked
+            expect(mockTable.insert.mock.calls.length).toBe(firstBatchCount);
+        });
+    });
+    describe('Normal logging behavior', () => {
+        it('should write logs to database for normal usage', async () => {
+            const { ConsoleLogs } = require('./console-logs.table');
+            await (0, console_logger_1.setupConsoleProxy)('test-process');
+            // Get fresh mock reference after setup
+            const mockTable = await ConsoleLogs();
+            mockTable.insert.mockClear();
+            console.log('Test message');
+            await new Promise(resolve => setTimeout(resolve, 50));
+            console.error('Test error');
+            await new Promise(resolve => setTimeout(resolve, 50));
+            console.warn('Test warning');
+            await new Promise(resolve => setTimeout(resolve, 50));
+            // Verify at least the logs were attempted
+            expect(mockTable.insert).toHaveBeenCalled();
+            expect(mockTable.insert.mock.calls.length).toBeGreaterThanOrEqual(1);
+            expect(mockTable.insert.mock.calls.length).toBeLessThanOrEqual(3);
+        });
+    });
+    describe('Logger class', () => {
+        beforeEach(() => {
+            // Reset state before each Logger test
+            (0, console_logger_1.resetLoggingState)();
+        });
+        it('should create logger with specified source', async () => {
+            const { ConsoleLogs } = require('./console-logs.table');
+            const mockTable = await ConsoleLogs();
+            (0, console_logger_1.markLoggingInitialized)();
+            const logger = new console_logger_1.Logger('MyModule');
+            mockTable.insert.mockClear();
+            logger.log('Test message');
+            await new Promise(resolve => setTimeout(resolve, 100));
+            expect(mockTable.insert).toHaveBeenCalled();
+            const call = mockTable.insert.mock.calls[0];
+            expect(call[0].source).toBe('MyModule');
+            expect(call[0].message).toBe('Test message');
+        });
+        it('should support all log levels', async () => {
+            const { ConsoleLogs } = require('./console-logs.table');
+            const mockTable = await ConsoleLogs();
+            (0, console_logger_1.markLoggingInitialized)();
+            const logger = new console_logger_1.Logger('TestModule');
+            mockTable.insert.mockClear();
+            logger.debug('Debug message');
+            await new Promise(resolve => setTimeout(resolve, 20));
+            logger.info('Info message');
+            await new Promise(resolve => setTimeout(resolve, 20));
+            logger.log('Log message');
+            await new Promise(resolve => setTimeout(resolve, 20));
+            logger.warn('Warn message');
+            await new Promise(resolve => setTimeout(resolve, 20));
+            logger.error('Error message');
+            await new Promise(resolve => setTimeout(resolve, 100));
+            // Should have most/all logs
+            expect(mockTable.insert.mock.calls.length).toBeGreaterThanOrEqual(4);
+            // Check that different levels were used
+            const levels = mockTable.insert.mock.calls.map((call) => call[0].level);
+            const uniqueLevels = new Set(levels);
+            expect(uniqueLevels.size).toBeGreaterThanOrEqual(4);
+        });
+        it('should queue logs before initialization', async () => {
+            const { ConsoleLogs } = require('./console-logs.table');
+            const mockTable = await ConsoleLogs();
+            // Ensure we're not initialized
+            // (resetLoggingState was called in beforeEach)
+            const logger = new console_logger_1.Logger('EarlyModule');
+            // Log before initialization
+            logger.log('Early message 1');
+            logger.warn('Early message 2');
+            logger.error('Early message 3');
+            // Small delay to ensure logs are queued
+            await new Promise(resolve => setTimeout(resolve, 50));
+            mockTable.insert.mockClear();
+            // Should not have written yet
+            expect(mockTable.insert).not.toHaveBeenCalled();
+            // Now initialize
+            (0, console_logger_1.markLoggingInitialized)();
+            // Wait for flush
+            await new Promise(resolve => setTimeout(resolve, 300));
+            // Should have flushed pending logs
+            expect(mockTable.insert.mock.calls.length).toBeGreaterThanOrEqual(2);
+        });
+        it('should write logs directly after initialization', async () => {
+            const { ConsoleLogs } = require('./console-logs.table');
+            const mockTable = await ConsoleLogs();
+            (0, console_logger_1.markLoggingInitialized)();
+            const logger = new console_logger_1.Logger('LateModule');
+            mockTable.insert.mockClear();
+            logger.log('Direct message');
+            await new Promise(resolve => setTimeout(resolve, 100));
+            expect(mockTable.insert).toHaveBeenCalledTimes(1);
+            expect(mockTable.insert.mock.calls[0][0].message).toBe('Direct message');
+        });
+        it('should use reliable source from constructor', async () => {
+            const { ConsoleLogs } = require('./console-logs.table');
+            const mockTable = await ConsoleLogs();
+            (0, console_logger_1.markLoggingInitialized)();
+            const logger1 = new console_logger_1.Logger('SourceA');
+            const logger2 = new console_logger_1.Logger('SourceB');
+            mockTable.insert.mockClear();
+            logger1.log('From A');
+            await new Promise(resolve => setTimeout(resolve, 50));
+            logger2.log('From B');
+            await new Promise(resolve => setTimeout(resolve, 100));
+            expect(mockTable.insert).toHaveBeenCalledTimes(2);
+            expect(mockTable.insert.mock.calls[0][0].source).toBe('SourceA');
+            expect(mockTable.insert.mock.calls[1][0].source).toBe('SourceB');
+        });
+    });
+});

package/dist/logging/console-logs.table.d.ts

@@ -13,9 +13,9 @@ export declare const consoleLogSchema: z.ZodObject<{
     stackTrace: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     message: string;
+    level: "error" | "debug" | "info" | "log" | "warn";
     timestamp: number;
     logId: string;
-    level: "error" | "debug" | "info" | "log" | "warn";
     process: string;
     processInstanceId: string;
     source?: string | undefined;
@@ -23,8 +23,8 @@ export declare const consoleLogSchema: z.ZodObject<{
     stackTrace?: string | undefined;
 }, {
     message: string;
-    logId: string;
     level: "error" | "debug" | "info" | "log" | "warn";
+    logId: string;
     process: string;
     processInstanceId: string;
     source?: string | undefined;

package/dist/logging/logger-example.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Example usage of the Logger class
+ *
+ * This file demonstrates how to use the Logger class for reliable, source-specific logging
+ */
+/**
+ * Example function that uses the logger
+ */
+export declare function processData(data: any): void;
+/**
+ * Example initialization flow
+ */
+export declare function initializeApp(): Promise<void>;
+/**
+ * Benefits of using Logger class:
+ *
+ * 1. **Reliable Source Tracking**: Source is set once at construction time,
+ *    not extracted from stack traces which can be unreliable
+ *
+ * 2. **Initialization Safety**: Logs before system is ready are queued and
+ *    flushed once markLoggingInitialized() is called
+ *
+ * 3. **Infinite Loop Protection**: Inherits all the cross-process and
+ *    single-process infinite loop detection
+ *
+ * 4. **Type Safety**: Full TypeScript support with proper typing
+ *
+ * 5. **Console Passthrough**: All logs still appear in the console immediately,
+ *    database writes happen asynchronously
+ *
+ * Usage pattern:
+ * ```typescript
+ * // At the top of each file:
+ * const logger = new Logger('FeatureName');
+ *
+ * // Throughout your code:
+ * logger.log('Something happened');
+ * logger.error('Something went wrong', error);
+ * logger.debug('Detailed debugging info', { context });
+ * ```
+ */