@elementor/angie-logger

A shared logger utility for Angie AI Assistant.

This package provides a flexible, context-aware logger with granular log level control.

Features

• Granular log levels: Control logging with 5 levels: debug, info, warn, error, none
• Context-aware: Supports string and object-based contexts that can be nested
• Dynamic control: Change log levels at runtime with setLogLevel()
• Type-safe: Written in TypeScript with full type definitions
• Zero dependencies: No runtime dependencies, lightweight bundle
• Environment agnostic: No built-in environment detection - you decide the log level

Installation

npm install @elementor/angie-logger

Quick Start

Basic Usage

import { createLogger } from '@elementor/angie-logger';

const logger = createLogger('MyApp');

logger.debug('Detailed debug information');
logger.log('General log message');
logger.info('Informational message');
logger.warn('Warning message');
logger.error('Error message');

Setting Log Levels

import { createLogger } from '@elementor/angie-logger';

const logger = createLogger('MyApp');

// Set to only show warnings and errors
logger.setLogLevel('warn');

logger.debug('Not logged');
logger.info('Not logged');
logger.warn('This WILL be logged');
logger.error('This WILL be logged');

With Context Objects

const logger = createLogger({ app: 'MyApp', version: '1.0.0' });

logger.info('Application initialized');
// Output: [{"app":"MyApp","version":"1.0.0"}] Application initialized

Extending Loggers

const baseLogger = createLogger('MyApp');
const moduleLogger = baseLogger.extend('UserModule');
const componentLogger = moduleLogger.extend('LoginForm');

componentLogger.log('Form rendered');
// Output: [MyApp > UserModule > LoginForm] Form rendered

Mixed Context Types

const appLogger = createLogger('MyApp');
const featureLogger = appLogger.extend({ feature: 'Authentication', userId: 123 });

featureLogger.info('User authenticated');
// Output: [MyApp > {"feature":"Authentication","userId":123}] User authenticated

Environment-Based Log Levels

import { createLogger } from '@elementor/angie-logger';

const logger = createLogger('MyApp');

// Set log level based on environment
if (process.env.NODE_ENV === 'production') {
  logger.setLogLevel('warn'); // Only warnings and errors in production
} else if (process.env.NODE_ENV === 'test') {
  logger.setLogLevel('none'); // Silent during tests
}
// Development: default 'debug' level shows everything

URL Parameter Debug Mode

const logger = createLogger('MyApp', { logLevel: 'warn' });

const params = new URLSearchParams(window.location.search);
if (params.has('debug')) {
  logger.setLogLevel('debug');
}

Configuration Options

You can customize logger behavior by passing a configuration object:

import { createLogger, LoggerConfig, LogLevel } from '@elementor/angie-logger';

const config: LoggerConfig = {
  logLevel: 'info',        // Set initial log level
  color: '#ff6b6b',        // Custom color for context labels
};

const logger = createLogger('MyApp', config);

Available Configuration Options

• logLevel (LogLevel, default: 'debug'): Initial log level

  const logger = createLogger('MyApp', { logLevel: 'warn' });
  logger.info('This will NOT be logged');
  logger.warn('This WILL be logged');

• color (string, default: '#00bcd4'): Color for the context label in browser console

  const logger = createLogger('MyApp', { color: '#ff6b6b' });

Note: Configuration is preserved when extending loggers:

const baseLogger = createLogger('App', { logLevel: 'warn', color: '#00ff00' });
const childLogger = baseLogger.extend('Module'); // Keeps the log level and color

Behavior

Log Levels

The logger supports 5 log levels with decreasing verbosity:

1. debug (default): All messages are logged (debug, log, info, warn, error)
2. info: Informational messages and above (log, info, warn, error)
3. warn: Warnings and errors only (warn, error)
4. error: Errors only (error)
5. none: Nothing is logged (complete silence)

Log Level Priority

Each level includes all messages from higher priority levels:

const logger = createLogger('MyApp');

// debug level (default) - logs everything
logger.setLogLevel('debug');
logger.debug('✓ Logged');
logger.log('✓ Logged');
logger.info('✓ Logged');
logger.warn('✓ Logged');
logger.error('✓ Logged');

// info level - logs info, log, warn, error
logger.setLogLevel('info');
logger.debug('✗ Not logged');
logger.log('✓ Logged');
logger.info('✓ Logged');
logger.warn('✓ Logged');
logger.error('✓ Logged');

// warn level - logs warn, error
logger.setLogLevel('warn');
logger.debug('✗ Not logged');
logger.log('✗ Not logged');
logger.info('✗ Not logged');
logger.warn('✓ Logged');
logger.error('✓ Logged');

// error level - logs error only
logger.setLogLevel('error');
logger.debug('✗ Not logged');
logger.log('✗ Not logged');
logger.info('✗ Not logged');
logger.warn('✗ Not logged');
logger.error('✓ Logged');

// none level - logs nothing
logger.setLogLevel('none');
logger.error('✗ Not logged');

Method to Level Mapping

• debug() → debug level
• log() → info level
• info() → info level
• warn() → warn level
• error() → error level

API Reference

createLogger(context, config?)

Creates a new logger instance.

Parameters:

• context: string | Record<string, unknown> - Initial context for the logger
• config?: LoggerConfig (optional) - Configuration options
  • logLevel?: LogLevel - Initial log level (default: 'debug')
  • color?: string - Color for context labels (default: '#00bcd4')

Returns: Logger instance

Logger Methods

• log(...args): General purpose logging (info level)
• info(...args): Informational messages (info level)
• warn(...args): Warning messages (warn level)
• error(...args): Error messages (error level)
• debug(...args): Debug messages (debug level)
• extend(subContext): Create a child logger with additional context
• setLogLevel(level): Dynamically change the log level

LogLevel Type

type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';

Examples

React Component

import { createLogger } from '@elementor/angie-logger';

const logger = createLogger('ImageGallery');

if (process.env.NODE_ENV === 'production') {
  logger.setLogLevel('error');
}

function ImageGallery() {
  logger.debug('Component mounting');
  
  const handleImageLoad = (imageId: string) => {
    logger.info('Image loaded', { imageId });
  };
  
  const handleError = (error: Error) => {
    logger.error('Failed to load image', error);
  };
  
  return (
    // component JSX
  );
}

Service Layer

import { createLogger } from '@elementor/angie-logger';

const logger = createLogger({ service: 'ApiClient' });

class ApiClient {
  private logger = logger.extend({ method: 'fetch' });
  
  async fetch(endpoint: string) {
    this.logger.debug('Fetching data', { endpoint });
    
    try {
      const response = await fetch(endpoint);
      this.logger.info('Data fetched successfully', { endpoint });
      return response.json();
    } catch (error) {
      this.logger.error('Failed to fetch data', { endpoint, error });
      throw error;
    }
  }
}

Dynamic Logging Control

import { createLogger } from '@elementor/angie-logger';

const logger = createLogger('App');

// Expose methods globally for debugging
if (typeof window !== 'undefined') {
  window.setLogLevel = (level) => logger.setLogLevel(level);
}

// Then in browser console:
// window.setLogLevel('debug')  // Show all logs
// window.setLogLevel('warn')   // Only warnings and errors
// window.setLogLevel('none')   // Silence all logs

Testing

import { createLogger } from '@elementor/angie-logger';

describe('MyComponent', () => {
  beforeAll(() => {
    // Silence logs during tests
    const logger = createLogger('MyComponent');
    logger.setLogLevel('none');
  });
  
  // your tests
});

Different Log Levels per Module

import { createLogger } from '@elementor/angie-logger';

const apiLogger = createLogger('API', { logLevel: 'warn' });
const uiLogger = createLogger('UI', { logLevel: 'debug' });

apiLogger.info('Not logged - API is warn level');
apiLogger.error('Logged - error is >= warn');

uiLogger.info('Logged - UI is debug level');
uiLogger.debug('Logged - UI is debug level');