Logger Type

Description

This example demonstrates the Logger interface for consistent logging across the AlgoKit Utils SDK. Topics covered:

Logger type definition with all log levels
Console-based Logger implementation
No-op (silent) logger for production
Custom formatting logger
Compatibility with common logging patterns

Prerequisites

No LocalNet required

Run This Example

From the repository root:

cd examples
npm run example common/06-logger.ts

Code

View source on GitHub

/**
 * Example: Logger Type
 *
 * This example demonstrates the Logger interface for consistent logging
 * across the AlgoKit Utils SDK.
 *
 * Topics covered:
 * - Logger type definition with all log levels
 * - Console-based Logger implementation
 * - No-op (silent) logger for production
 * - Custom formatting logger
 * - Compatibility with common logging patterns
 *
 * Prerequisites:
 * - No LocalNet required
 */

import type { Logger } from '@algorandfoundation/algokit-utils/common';
import { printHeader, printInfo, printStep, printSuccess } from '../shared/utils.js';

// ============================================================================
// Main Example
// ============================================================================

printHeader('Logger Type Example');

// ============================================================================
// Step 1: Logger Type Definition
// ============================================================================
printStep(1, 'Logger Type Definition');

printInfo('The Logger type defines a standard logging interface:');
printInfo('');
printInfo('  type Logger = {');
printInfo('    error(message: string, ...optionalParams: unknown[]): void');
printInfo('    warn(message: string, ...optionalParams: unknown[]): void');
printInfo('    info(message: string, ...optionalParams: unknown[]): void');
printInfo('    verbose(message: string, ...optionalParams: unknown[]): void');
printInfo('    debug(message: string, ...optionalParams: unknown[]): void');
printInfo('  }');
printInfo('');
printInfo('Log levels (from most to least severe):');
printInfo('  1. error   - Critical errors that need immediate attention');
printInfo('  2. warn    - Warning conditions that should be reviewed');
printInfo('  3. info    - Informational messages for normal operations');
printInfo('  4. verbose - Detailed tracing for troubleshooting');
printInfo('  5. debug   - Developer debugging information');
printSuccess('Logger interface provides 5 standard log levels');

// ============================================================================
// Step 2: Console-based Logger Implementation
// ============================================================================
printStep(2, 'Console-based Logger Implementation');

const consoleLogger: Logger = {
  error: (message: string, ...optionalParams: unknown[]) => {
    console.error(`[ERROR] ${message}`, ...optionalParams);
  },
  warn: (message: string, ...optionalParams: unknown[]) => {
    console.warn(`[WARN]  ${message}`, ...optionalParams);
  },
  info: (message: string, ...optionalParams: unknown[]) => {
    console.info(`[INFO]  ${message}`, ...optionalParams);
  },
  verbose: (message: string, ...optionalParams: unknown[]) => {
    console.log(`[VERB]  ${message}`, ...optionalParams);
  },
  debug: (message: string, ...optionalParams: unknown[]) => {
    console.debug(`[DEBUG] ${message}`, ...optionalParams);
  },
};

printInfo('Created a console-based Logger implementation');
printInfo('Demonstrating each log level:');
console.log(''); // blank line for readability

consoleLogger.error('Database connection failed', { code: 'ECONNREFUSED', port: 5432 });
consoleLogger.warn('API rate limit approaching', { current: 95, limit: 100 });
consoleLogger.info('Transaction submitted', { txId: 'ABC123...' });
consoleLogger.verbose('Processing block', { round: 12345, txCount: 7 });
consoleLogger.debug('Raw response payload', { bytes: 1024 });

console.log(''); // blank line for readability
printSuccess('All 5 log levels demonstrated');

// ============================================================================
// Step 3: No-op (Silent) Logger
// ============================================================================
printStep(3, 'No-op (Silent) Logger');

const nullLogger: Logger = {
  error: () => {},
  warn: () => {},
  info: () => {},
  verbose: () => {},
  debug: () => {},
};

printInfo('Created a no-op (silent) logger');
printInfo('Silent loggers are useful for:');
printInfo('  - Production environments where logging is disabled');
printInfo('  - Unit tests where log output is not wanted');
printInfo('  - Default parameter values when no logger is provided');
printInfo('');
printInfo('Calling silent logger (no output expected):');
nullLogger.error('This error will not be logged');
nullLogger.warn('This warning will not be logged');
nullLogger.info('This info will not be logged');
nullLogger.verbose('This verbose message will not be logged');
nullLogger.debug('This debug message will not be logged');
printSuccess('No-op logger created - produces no output');

// ============================================================================
// Step 4: Custom Formatting Logger
// ============================================================================
printStep(4, 'Custom Formatting Logger');

function createTimestampLogger(prefix: string): Logger {
  const formatMessage = (level: string, message: string): string => {
    const timestamp = new Date().toISOString();
    return `${timestamp} [${prefix}] ${level.padEnd(7)} ${message}`;
  };

  return {
    error: (message: string, ...optionalParams: unknown[]) => {
      console.error(formatMessage('ERROR', message), ...optionalParams);
    },
    warn: (message: string, ...optionalParams: unknown[]) => {
      console.warn(formatMessage('WARN', message), ...optionalParams);
    },
    info: (message: string, ...optionalParams: unknown[]) => {
      console.info(formatMessage('INFO', message), ...optionalParams);
    },
    verbose: (message: string, ...optionalParams: unknown[]) => {
      console.log(formatMessage('VERBOSE', message), ...optionalParams);
    },
    debug: (message: string, ...optionalParams: unknown[]) => {
      console.debug(formatMessage('DEBUG', message), ...optionalParams);
    },
  };
}

const appLogger = createTimestampLogger('MyApp');

printInfo('Created a logger with custom formatting:');
printInfo('  - ISO timestamp prefix');
printInfo('  - Application name prefix');
printInfo('  - Padded log level for alignment');
printInfo('');
printInfo('Demonstrating custom formatted output:');
console.log(''); // blank line for readability

appLogger.info('Application started');
appLogger.debug('Configuration loaded', { env: 'development' });
appLogger.warn('Deprecated API endpoint called');

console.log(''); // blank line for readability
printSuccess('Custom formatting logger created and demonstrated');

// ============================================================================
// Step 5: Level-filtered Logger
// ============================================================================
printStep(5, 'Level-filtered Logger');

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

const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
  error: 0,
  warn: 1,
  info: 2,
  verbose: 3,
  debug: 4,
};

function createFilteredLogger(minLevel: LogLevel): Logger {
  const minPriority = LOG_LEVEL_PRIORITY[minLevel];

  const shouldLog = (level: LogLevel): boolean => {
    return LOG_LEVEL_PRIORITY[level] <= minPriority;
  };

  return {
    error: (message: string, ...optionalParams: unknown[]) => {
      if (shouldLog('error')) console.error(`[ERROR] ${message}`, ...optionalParams);
    },
    warn: (message: string, ...optionalParams: unknown[]) => {
      if (shouldLog('warn')) console.warn(`[WARN]  ${message}`, ...optionalParams);
    },
    info: (message: string, ...optionalParams: unknown[]) => {
      if (shouldLog('info')) console.info(`[INFO]  ${message}`, ...optionalParams);
    },
    verbose: (message: string, ...optionalParams: unknown[]) => {
      if (shouldLog('verbose')) console.log(`[VERB]  ${message}`, ...optionalParams);
    },
    debug: (message: string, ...optionalParams: unknown[]) => {
      if (shouldLog('debug')) console.debug(`[DEBUG] ${message}`, ...optionalParams);
    },
  };
}

printInfo('Created a level-filtered logger factory');
printInfo('Filter levels control which messages are logged:');
printInfo('  - "error"   -> only errors');
printInfo('  - "warn"    -> errors + warnings');
printInfo('  - "info"    -> errors + warnings + info');
printInfo('  - "verbose" -> all except debug');
printInfo('  - "debug"   -> all messages');
printInfo('');

printInfo('Testing with minLevel="warn" (only error and warn):');
const warnLogger = createFilteredLogger('warn');
console.log(''); // blank line for readability
warnLogger.error('This error IS logged');
warnLogger.warn('This warning IS logged');
warnLogger.info('This info is NOT logged');
warnLogger.debug('This debug is NOT logged');

console.log(''); // blank line for readability
printSuccess('Level-filtered logger demonstrated');

// ============================================================================
// Step 6: Logger Interface Compatibility
// ============================================================================
printStep(6, 'Logger Interface Compatibility');

printInfo('The Logger interface is compatible with common logging libraries:');
printInfo('');
printInfo('  1. Console API - native JavaScript console methods');
printInfo('     const logger: Logger = { ...console, verbose: console.log }');
printInfo('');
printInfo('  2. Winston - popular Node.js logging library');
printInfo('     const winston = require("winston")');
printInfo('     const logger: Logger = winston.createLogger(...)');
printInfo('');
printInfo('  3. Pino - fast JSON logger for Node.js');
printInfo('     const pino = require("pino")');
printInfo('     const logger: Logger = pino()');
printInfo('');
printInfo('  4. Custom implementations - as shown in this example');
printInfo('');

// Demonstrate that native console can be adapted as a Logger
printInfo('Demonstrating console adapted as Logger:');
const nativeConsoleLogger: Logger = {
  ...console,
  verbose: console.log.bind(console), // Console doesn't have verbose, so use log
};
console.log(''); // blank line for readability
nativeConsoleLogger.info('Native console.info works as Logger.info');
nativeConsoleLogger.debug('Native console.debug works as Logger.debug');

console.log(''); // blank line for readability
printSuccess('Console can be adapted to Logger interface (needs verbose wrapper)');

// ============================================================================
// Step 7: Using Logger in Functions
// ============================================================================
printStep(7, 'Using Logger in Functions');

function simulateTransaction(txId: string, logger: Logger = nullLogger): void {
  logger.info(`Starting transaction: ${txId}`);
  logger.debug('Validating transaction parameters');
  logger.verbose('Serializing transaction data');
  logger.info(`Transaction ${txId} completed successfully`);
}

printInfo('Created a function that accepts Logger as optional parameter');
printInfo('When no logger is provided, it defaults to nullLogger (silent)');
printInfo('');

printInfo('Calling with no logger (silent):');
simulateTransaction('TX-001');
printInfo('  (no output produced)');
printInfo('');

printInfo('Calling with consoleLogger:');
console.log(''); // blank line for readability
simulateTransaction('TX-002', consoleLogger);

console.log(''); // blank line for readability
printSuccess('Logger can be used as optional dependency injection');

// ============================================================================
// Summary
// ============================================================================
printStep(8, 'Summary');

printInfo('Logger interface provides:');
printInfo('  - 5 standard log levels (error, warn, info, verbose, debug)');
printInfo('  - Support for additional parameters (objects, arrays, etc.)');
printInfo('  - Compatibility with console, Winston, Pino, and others');
printInfo('  - Easy to implement custom formatters and filters');
printInfo('  - No-op logger for disabling output');
printInfo('');
printSuccess('Logger Type Example completed!');

Logger Type

Description

Prerequisites

Run This Example

Code

Other examples in Common Utilities