@xiboplayer/utils 0.1.0

package/src/logger.js

@@ -0,0 +1,237 @@
+/**
+ * Configurable Logger for Xibo Players
+ *
+ * Supports log levels: DEBUG, INFO, WARNING, ERROR, NONE
+ *
+ * Level precedence (highest wins):
+ *   1. URL param ?logLevel=DEBUG
+ *   2. localStorage xibo_log_level
+ *   3. CMS setting via RegisterDisplay (call applyCmsLogLevel())
+ *   4. Default: DEBUG on localhost, INFO in production
+ *
+ * Loggers created without an explicit level are REACTIVE — they follow
+ * the global level at call time, so setLogLevel() affects all of them.
+ */
+
+const LOG_LEVELS = {
+  DEBUG: 0,
+  INFO: 1,
+  WARNING: 2,
+  ERROR: 3,
+  NONE: 4
+};
+
+// Log sink system — external consumers (e.g., LogReporter) can intercept all log output
+const logSinks = [];
+
+class Logger {
+  /**
+   * @param {string} name - Logger name (shown in prefix)
+   * @param {string|null} level - Explicit level string, or null to follow global
+   */
+  constructor(name, level = null) {
+    this.name = name;
+    this.useGlobal = (level === null);
+    if (!this.useGlobal) {
+      this.setLevel(level);
+    }
+  }
+
+  setLevel(level) {
+    this.useGlobal = false;
+    if (typeof level === 'string') {
+      this.level = LOG_LEVELS[level.toUpperCase()] ?? LOG_LEVELS.INFO;
+    } else {
+      this.level = level;
+    }
+  }
+
+  /** Effective level: own override or global */
+  getEffectiveLevel() {
+    return this.useGlobal ? globalConfig.level : this.level;
+  }
+
+  debug(...args) {
+    if (this.getEffectiveLevel() <= LOG_LEVELS.DEBUG) {
+      console.log(`[${this.name}] DEBUG:`, ...args);
+    }
+    _dispatchToSinks('debug', this.name, args);
+  }
+
+  info(...args) {
+    if (this.getEffectiveLevel() <= LOG_LEVELS.INFO) {
+      console.log(`[${this.name}]`, ...args);
+    }
+    _dispatchToSinks('info', this.name, args);
+  }
+
+  warn(...args) {
+    if (this.getEffectiveLevel() <= LOG_LEVELS.WARNING) {
+      console.warn(`[${this.name}]`, ...args);
+    }
+    _dispatchToSinks('warning', this.name, args);
+  }
+
+  error(...args) {
+    if (this.getEffectiveLevel() <= LOG_LEVELS.ERROR) {
+      console.error(`[${this.name}]`, ...args);
+    }
+    _dispatchToSinks('error', this.name, args);
+  }
+
+  // Convenience method for conditional logging
+  log(level, ...args) {
+    switch (level.toUpperCase()) {
+      case 'DEBUG': return this.debug(...args);
+      case 'INFO': return this.info(...args);
+      case 'WARNING':
+      case 'WARN': return this.warn(...args);
+      case 'ERROR': return this.error(...args);
+    }
+  }
+}
+
+// Global log level configuration
+const globalConfig = {
+  level: LOG_LEVELS.INFO, // Default: INFO and above
+
+  setGlobalLevel(level) {
+    if (typeof level === 'string') {
+      this.level = LOG_LEVELS[level.toUpperCase()] ?? LOG_LEVELS.INFO;
+    } else {
+      this.level = level;
+    }
+
+    console.log(`[Logger] Global log level set to: ${this.getLevelName(this.level)}`);
+  },
+
+  getLevelName(level) {
+    return Object.keys(LOG_LEVELS).find(key => LOG_LEVELS[key] === level) || 'UNKNOWN';
+  }
+};
+
+// Track whether the level was set by a local override (URL param / localStorage)
+let hasLocalOverride = false;
+
+// Set global level from environment or localStorage
+if (typeof window !== 'undefined') {
+  const urlParams = new URLSearchParams(window.location.search);
+  const urlLevel = urlParams.get('logLevel');
+  const storageLevel = localStorage.getItem('xibo_log_level');
+
+  if (urlLevel) {
+    globalConfig.setGlobalLevel(urlLevel);
+    hasLocalOverride = true;
+  } else if (storageLevel) {
+    globalConfig.setGlobalLevel(storageLevel);
+    hasLocalOverride = true;
+  } else if (window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1') {
+    // Development mode - debug logging
+    globalConfig.setGlobalLevel('DEBUG');
+  } else {
+    // Production mode - INFO by default (CMS can override later)
+    globalConfig.setGlobalLevel('INFO');
+  }
+}
+
+// Factory function — loggers follow global level by default (reactive)
+export function createLogger(name, level = null) {
+  return new Logger(name, level);
+}
+
+// Set global log level (and persist to localStorage)
+export function setLogLevel(level) {
+  globalConfig.setGlobalLevel(level);
+
+  // Save to localStorage
+  if (typeof window !== 'undefined') {
+    localStorage.setItem('xibo_log_level', level.toUpperCase());
+  }
+}
+
+// Get current log level name
+export function getLogLevel() {
+  return globalConfig.getLevelName(globalConfig.level);
+}
+
+/**
+ * Returns true when the effective global level is DEBUG.
+ * Use this for conditional debug features (video controls, overlays, etc.)
+ */
+export function isDebug() {
+  return globalConfig.level <= LOG_LEVELS.DEBUG;
+}
+
+/**
+ * Apply CMS logLevel setting — only if no local override (URL/localStorage) exists.
+ * @param {string} cmsLevel - CMS level string: 'error', 'audit', 'info', 'debug'
+ * @returns {boolean} true if the level was applied
+ */
+export function applyCmsLogLevel(cmsLevel) {
+  if (hasLocalOverride) return false;
+  if (!cmsLevel) return false;
+
+  const mapped = mapCmsLogLevel(cmsLevel);
+  globalConfig.setGlobalLevel(mapped);
+  return true;
+}
+
+/**
+ * Map CMS logLevel strings to internal level names.
+ * CMS uses: 'emergency','alert','critical','error','warning','notice','info','debug','audit'
+ * We collapse them to our 4 levels.
+ */
+export function mapCmsLogLevel(cmsLevel) {
+  switch ((cmsLevel || '').toLowerCase()) {
+    case 'debug':
+      return 'DEBUG';
+    case 'info':
+    case 'notice':
+    case 'audit':
+      return 'INFO';
+    case 'warning':
+      return 'WARNING';
+    case 'error':
+    case 'critical':
+    case 'alert':
+    case 'emergency':
+      return 'ERROR';
+    default:
+      return 'INFO';
+  }
+}
+
+/**
+ * Dispatch log entry to all registered sinks.
+ * Sinks receive { level, name, args } and should not throw.
+ * @private
+ */
+function _dispatchToSinks(level, name, args) {
+  if (logSinks.length === 0) return;
+  for (const fn of logSinks) {
+    try {
+      fn({ level, name, args });
+    } catch (_) {
+      // Sink errors must never break logging
+    }
+  }
+}
+
+/**
+ * Register a log sink — receives all log output regardless of level filtering.
+ * @param {function} fn - Callback: ({ level, name, args }) => void
+ */
+export function registerLogSink(fn) {
+  logSinks.push(fn);
+}
+
+/**
+ * Unregister a previously registered log sink.
+ * @param {function} fn - The same function reference passed to registerLogSink
+ */
+export function unregisterLogSink(fn) {
+  const idx = logSinks.indexOf(fn);
+  if (idx >= 0) logSinks.splice(idx, 1);
+}
+
+export { LOG_LEVELS };

package/src/logger.test.js

@@ -0,0 +1,477 @@
+/**
+ * Logger Tests
+ *
+ * Tests for configurable logging with log levels
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { createLogger, setLogLevel, getLogLevel, LOG_LEVELS } from './logger.js';
+
+describe('Logger', () => {
+  let consoleLogSpy;
+  let consoleWarnSpy;
+  let consoleErrorSpy;
+
+  beforeEach(() => {
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('Log Levels', () => {
+    it('should have correct log level hierarchy', () => {
+      expect(LOG_LEVELS.DEBUG).toBe(0);
+      expect(LOG_LEVELS.INFO).toBe(1);
+      expect(LOG_LEVELS.WARNING).toBe(2);
+      expect(LOG_LEVELS.ERROR).toBe(3);
+      expect(LOG_LEVELS.NONE).toBe(4);
+    });
+  });
+
+  describe('Logger Creation', () => {
+    it('should create logger with default INFO level', () => {
+      const logger = createLogger('TestModule');
+
+      expect(logger.name).toBe('TestModule');
+      // When no explicit level is given, logger follows global level (useGlobal=true)
+      // so logger.level is undefined — check getEffectiveLevel() instead
+      expect(logger.getEffectiveLevel()).toBeLessThanOrEqual(LOG_LEVELS.INFO);
+    });
+
+    it('should create logger with custom level', () => {
+      const logger = createLogger('TestModule', 'DEBUG');
+
+      expect(logger.level).toBe(LOG_LEVELS.DEBUG);
+    });
+
+    it('should create logger with numeric level', () => {
+      const logger = createLogger('TestModule', LOG_LEVELS.WARNING);
+
+      expect(logger.level).toBe(LOG_LEVELS.WARNING);
+    });
+  });
+
+  describe('debug()', () => {
+    it('should log at DEBUG level', () => {
+      const logger = createLogger('Test', 'DEBUG');
+
+      logger.debug('Debug message', { data: 'value' });
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '[Test] DEBUG:',
+        'Debug message',
+        { data: 'value' }
+      );
+    });
+
+    it('should not log when level is INFO', () => {
+      const logger = createLogger('Test', 'INFO');
+
+      logger.debug('Debug message');
+
+      expect(consoleLogSpy).not.toHaveBeenCalled();
+    });
+
+    it('should not log when level is WARNING', () => {
+      const logger = createLogger('Test', 'WARNING');
+
+      logger.debug('Debug message');
+
+      expect(consoleLogSpy).not.toHaveBeenCalled();
+    });
+
+    it('should not log when level is ERROR', () => {
+      const logger = createLogger('Test', 'ERROR');
+
+      logger.debug('Debug message');
+
+      expect(consoleLogSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('info()', () => {
+    it('should log at INFO level', () => {
+      const logger = createLogger('Test', 'INFO');
+
+      logger.info('Info message', 'arg1', 'arg2');
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '[Test]',
+        'Info message',
+        'arg1',
+        'arg2'
+      );
+    });
+
+    it('should log when level is DEBUG', () => {
+      const logger = createLogger('Test', 'DEBUG');
+
+      logger.info('Info message');
+
+      expect(consoleLogSpy).toHaveBeenCalled();
+    });
+
+    it('should not log when level is WARNING', () => {
+      const logger = createLogger('Test', 'WARNING');
+
+      logger.info('Info message');
+
+      expect(consoleLogSpy).not.toHaveBeenCalled();
+    });
+
+    it('should not log when level is ERROR', () => {
+      const logger = createLogger('Test', 'ERROR');
+
+      logger.info('Info message');
+
+      expect(consoleLogSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('warn()', () => {
+    it('should log at WARNING level', () => {
+      const logger = createLogger('Test', 'WARNING');
+
+      logger.warn('Warning message', { warn: true });
+
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        '[Test]',
+        'Warning message',
+        { warn: true }
+      );
+    });
+
+    it('should log when level is DEBUG', () => {
+      const logger = createLogger('Test', 'DEBUG');
+
+      logger.warn('Warning');
+
+      expect(consoleWarnSpy).toHaveBeenCalled();
+    });
+
+    it('should log when level is INFO', () => {
+      const logger = createLogger('Test', 'INFO');
+
+      logger.warn('Warning');
+
+      expect(consoleWarnSpy).toHaveBeenCalled();
+    });
+
+    it('should not log when level is ERROR', () => {
+      const logger = createLogger('Test', 'ERROR');
+
+      logger.warn('Warning');
+
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('error()', () => {
+    it('should log at ERROR level', () => {
+      const logger = createLogger('Test', 'ERROR');
+
+      logger.error('Error message', new Error('Test error'));
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        '[Test]',
+        'Error message',
+        expect.any(Error)
+      );
+    });
+
+    it('should log when level is DEBUG', () => {
+      const logger = createLogger('Test', 'DEBUG');
+
+      logger.error('Error');
+
+      expect(consoleErrorSpy).toHaveBeenCalled();
+    });
+
+    it('should log when level is INFO', () => {
+      const logger = createLogger('Test', 'INFO');
+
+      logger.error('Error');
+
+      expect(consoleErrorSpy).toHaveBeenCalled();
+    });
+
+    it('should log when level is WARNING', () => {
+      const logger = createLogger('Test', 'WARNING');
+
+      logger.error('Error');
+
+      expect(consoleErrorSpy).toHaveBeenCalled();
+    });
+
+    it('should not log when level is NONE', () => {
+      const logger = createLogger('Test', 'NONE');
+
+      logger.error('Error');
+
+      expect(consoleErrorSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('log(level, ...)', () => {
+    let logger;
+
+    beforeEach(() => {
+      logger = createLogger('Test', 'DEBUG');
+    });
+
+    it('should delegate to debug()', () => {
+      logger.log('DEBUG', 'message');
+
+      expect(consoleLogSpy).toHaveBeenCalledWith('[Test] DEBUG:', 'message');
+    });
+
+    it('should delegate to info()', () => {
+      logger.log('INFO', 'message');
+
+      expect(consoleLogSpy).toHaveBeenCalledWith('[Test]', 'message');
+    });
+
+    it('should delegate to warn() for WARNING', () => {
+      logger.log('WARNING', 'message');
+
+      expect(consoleWarnSpy).toHaveBeenCalledWith('[Test]', 'message');
+    });
+
+    it('should delegate to warn() for WARN', () => {
+      logger.log('WARN', 'message');
+
+      expect(consoleWarnSpy).toHaveBeenCalledWith('[Test]', 'message');
+    });
+
+    it('should delegate to error()', () => {
+      logger.log('ERROR', 'message');
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith('[Test]', 'message');
+    });
+
+    it('should handle lowercase level names', () => {
+      logger.log('debug', 'message');
+
+      expect(consoleLogSpy).toHaveBeenCalledWith('[Test] DEBUG:', 'message');
+    });
+  });
+
+  describe('setLevel()', () => {
+    let logger;
+
+    beforeEach(() => {
+      logger = createLogger('Test', 'INFO');
+    });
+
+    it('should change level from string', () => {
+      logger.setLevel('DEBUG');
+
+      expect(logger.level).toBe(LOG_LEVELS.DEBUG);
+    });
+
+    it('should change level from number', () => {
+      logger.setLevel(LOG_LEVELS.WARNING);
+
+      expect(logger.level).toBe(LOG_LEVELS.WARNING);
+    });
+
+    it('should handle lowercase level names', () => {
+      logger.setLevel('debug');
+
+      expect(logger.level).toBe(LOG_LEVELS.DEBUG);
+    });
+
+    it('should default to INFO for invalid level', () => {
+      logger.setLevel('INVALID');
+
+      expect(logger.level).toBe(LOG_LEVELS.INFO);
+    });
+
+    it('should affect subsequent log calls', () => {
+      logger.setLevel('ERROR');
+
+      logger.info('Should not log');
+      logger.error('Should log');
+
+      expect(consoleLogSpy).not.toHaveBeenCalled();
+      expect(consoleErrorSpy).toHaveBeenCalled();
+    });
+  });
+
+  describe('Global Log Level', () => {
+    it('should set global log level', () => {
+      setLogLevel('WARNING');
+
+      const level = getLogLevel();
+
+      expect(level).toBe('WARNING');
+    });
+
+    it('should affect new loggers', () => {
+      setLogLevel('ERROR');
+
+      // setLogLevel() internally calls console.log() to announce the level change,
+      // so reset the spy before testing actual logger behavior
+      consoleLogSpy.mockClear();
+
+      const logger = createLogger('NewLogger');
+
+      logger.info('Should not log');
+      logger.error('Should log');
+
+      expect(consoleLogSpy).not.toHaveBeenCalled();
+      expect(consoleErrorSpy).toHaveBeenCalled();
+    });
+
+    it('should handle lowercase in setLogLevel', () => {
+      setLogLevel('debug');
+
+      expect(getLogLevel()).toBe('DEBUG');
+    });
+  });
+
+  describe('Multiple Arguments', () => {
+    let logger;
+
+    beforeEach(() => {
+      logger = createLogger('Test', 'DEBUG');
+    });
+
+    it('should pass all arguments to console', () => {
+      logger.info('Message', 1, 'two', { three: 3 }, [4, 5]);
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '[Test]',
+        'Message',
+        1,
+        'two',
+        { three: 3 },
+        [4, 5]
+      );
+    });
+
+    it('should handle zero arguments', () => {
+      logger.info();
+
+      expect(consoleLogSpy).toHaveBeenCalledWith('[Test]');
+    });
+
+    it('should handle objects and errors', () => {
+      const error = new Error('Test');
+      const obj = { key: 'value' };
+
+      logger.error('Error:', error, obj);
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        '[Test]',
+        'Error:',
+        error,
+        obj
+      );
+    });
+  });
+
+  describe('Module Names', () => {
+    it('should prefix logs with module name', () => {
+      const logger = createLogger('MyModule', 'INFO');
+
+      logger.info('Test');
+
+      expect(consoleLogSpy).toHaveBeenCalledWith('[MyModule]', 'Test');
+    });
+
+    it('should support different module names', () => {
+      const logger1 = createLogger('Module1', 'INFO');
+      const logger2 = createLogger('Module2', 'INFO');
+
+      logger1.info('From 1');
+      logger2.info('From 2');
+
+      expect(consoleLogSpy).toHaveBeenCalledWith('[Module1]', 'From 1');
+      expect(consoleLogSpy).toHaveBeenCalledWith('[Module2]', 'From 2');
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle null module name', () => {
+      const logger = createLogger(null, 'INFO');
+
+      logger.info('Test');
+
+      expect(consoleLogSpy).toHaveBeenCalledWith('[null]', 'Test');
+    });
+
+    it('should handle undefined level (use default)', () => {
+      const logger = createLogger('Test', undefined);
+
+      // When level is undefined, logger follows global level (useGlobal=true)
+      // so logger.level is undefined — check getEffectiveLevel() instead
+      expect(logger.getEffectiveLevel()).toBeDefined();
+    });
+
+    it('should handle very long messages', () => {
+      const logger = createLogger('Test', 'INFO');
+      const longMessage = 'a'.repeat(10000);
+
+      logger.info(longMessage);
+
+      expect(consoleLogSpy).toHaveBeenCalledWith('[Test]', longMessage);
+    });
+
+    it('should handle circular references in objects', () => {
+      const logger = createLogger('Test', 'INFO');
+      const circular = { a: 1 };
+      circular.self = circular;
+
+      // Should not throw
+      expect(() => {
+        logger.info('Circular:', circular);
+      }).not.toThrow();
+    });
+  });
+
+  describe('Performance', () => {
+    it('should skip expensive operations when level too low', () => {
+      const logger = createLogger('Test', 'ERROR');
+
+      const expensiveOperation = vi.fn(() => {
+        return 'expensive result';
+      });
+
+      logger.debug('Debug:', expensiveOperation());
+
+      // expensiveOperation still called (JS evaluates args before function call)
+      // But console.log should not be called
+      expect(consoleLogSpy).not.toHaveBeenCalled();
+    });
+
+    it('should handle high volume logging', () => {
+      const logger = createLogger('Test', 'INFO');
+
+      for (let i = 0; i < 1000; i++) {
+        logger.info(`Message ${i}`);
+      }
+
+      expect(consoleLogSpy).toHaveBeenCalledTimes(1000);
+    });
+  });
+
+  describe('Logging Disabled (NONE)', () => {
+    it('should not log anything when level is NONE', () => {
+      const logger = createLogger('Test', 'NONE');
+
+      logger.debug('Debug');
+      logger.info('Info');
+      logger.warn('Warn');
+      logger.error('Error');
+
+      expect(consoleLogSpy).not.toHaveBeenCalled();
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+      expect(consoleErrorSpy).not.toHaveBeenCalled();
+    });
+  });
+});