Logger API

Logging system with multiple transports, log levels, and child logger support

Overview

The logger provides a flexible logging system with configurable transports (console, GitHub Actions), hierarchical child loggers, and multiple log levels.

Logger

Creates a new logger instance with the specified transport.

import { Logger } from './logger/index.mjs';

const logger = Logger('console');
const ghLogger = Logger('github');

Parameters

transportName · string · default: "console"

Name of the transport to use. Available options:

• 'console' - Standard console output with colors
• 'github' - GitHub Actions workflow commands

Returns

logger · LoggerInstance

Logger instance with logging methods

Throws

Throws an error if the specified transport is not found.

createLogger

Low-level function to create a logger with a custom transport function.

import { createLogger } from './logger/logger.mjs';
import { LogLevel } from './logger/constants.mjs';

const logger = createLogger(customTransport, LogLevel.info, 'myModule');

Parameters

transport · Transport · required

Function to handle log output. Receives a context object with:

• level (number) - Log level
• message (string) - Log message
• timestamp (number) - Unix timestamp
• metadata (object) - Additional metadata
• module (string) - Optional module name

loggerLevel · number · default: "LogLevel.info"

Minimum log level to output

module · string

Optional module name for the logger

Returns

logger · LoggerInstance

Logger instance with the following methods:

Show methods

info · (message, metadata?) => void

Log info message

warn · (message, metadata?) => void

Log warning message

error · (message, metadata?) => void

Log error message or Error object

fatal · (message, metadata?) => void

Log fatal error message

debug · (message, metadata?) => void

Log debug message

child · (module: string) => LoggerInstance

Create child logger for specific module

setLogLevel · (level: number | string) => void

Set log level for this logger and all children

Logging Methods

All logging methods accept a message and optional metadata object.

info

Logs an informational message.

logger.info('Processing file', { file: 'index.md' });

Source: logger/logger.mjs:84

warn

Logs a warning message.

logger.warn('Deprecated API usage detected');

Source: logger/logger.mjs:94

error

Logs an error message or Error object.

logger.error('Failed to parse file', { file: 'broken.md' });
logger.error(new Error('Parse error'));

Source: logger/logger.mjs:104

fatal

Logs a fatal error message.

logger.fatal('Critical system failure');

Source: logger/logger.mjs:114

debug

Logs a debug message (only visible when log level is debug).

logger.debug('Starting generator', { name: 'metadata' });

Source: logger/logger.mjs:124

Child Loggers

child

Creates a child logger for a specific module. Child loggers:

• Share the parent’s log level
• Inherit log level changes from parent
• Display module name in output

import logger from './logger/index.mjs';

const generatorLogger = logger.child('generators');
const metadataLogger = generatorLogger.child('metadata');

metadataLogger.info('Processing metadata');
// Output: [generators:metadata] Processing metadata

Source: logger/logger.mjs:134

Parameters

childModule · string · required

Module name for the child logger

Returns

childLogger · LoggerInstance

New child logger instance

Log Level Management

setLogLevel

Sets the log level for the logger and all its children. Changes propagate down the hierarchy.

import { LogLevel } from './logger/constants.mjs';

logger.setLogLevel(LogLevel.debug);
// or
logger.setLogLevel('debug');

Source: logger/logger.mjs:147

Parameters

level · number | string · required

Log level as number or string name (‘debug’, ‘info’, ‘warn’, ‘error’, ‘fatal’)

Log Levels

Log levels are defined in logger/constants.mjs:

import { LogLevel } from './logger/constants.mjs';

LogLevel.debug  // 10
LogLevel.info   // 20
LogLevel.warn   // 30
LogLevel.error  // 40
LogLevel.fatal  // 50

Messages are only logged if their level is greater than or equal to the current logger level.

Message Types

The logger accepts multiple message types:

type LogMessage = string | Error | string[];

String Message

logger.info('Processing complete');

Error Object

try {
  // ...
} catch (err) {
  logger.error(err); // Extracts message and stack
}

Array of Messages

logger.info([
  'File 1 processed',
  'File 2 processed',
  'File 3 processed',
]);

Metadata

All logging methods accept an optional metadata object:

interface Metadata {
  file?: {
    path: string;
    position?: {
      start: { line: number };
      end: { line: number };
    };
  };
  stack?: string;
  [key: string]: any;
}

Example with Metadata

logger.info('Parsing file', {
  file: {
    path: 'doc/api/fs.md',
    position: { start: { line: 10 }, end: { line: 50 } },
  },
  entries: 42,
});

Transports

Console Transport

Default transport with colored output for terminal.

import { Logger } from './logger/index.mjs';

const logger = Logger('console'); // or Logger() for default

Features:

• Color-coded log levels
• Formatted timestamps
• Module name display
• Stack trace formatting

GitHub Transport

For GitHub Actions workflow commands.

import { Logger } from './logger/index.mjs';

const logger = Logger('github');

Features:

• GitHub Actions annotations
• File/line number linking
• Workflow command formatting

Examples

Basic Usage

import logger from './logger/index.mjs';

logger.info('Application started');
logger.warn('Configuration file not found, using defaults');
logger.error('Failed to connect to database');

Module-Specific Logging

import logger from './logger/index.mjs';

const generatorLogger = logger.child('generators');
generatorLogger.debug('Scheduling "metadata"', {
  dependsOn: 'ast',
  streaming: true,
});

Source: generators.mjs:64

Error Logging with Context

try {
  await parseFile(filePath);
} catch (err) {
  logger.error(err, {
    file: { path: filePath },
    operation: 'parse',
  });
}

Dynamic Log Level

import { LogLevel } from './logger/constants.mjs';

// Enable debug logging in development
if (process.env.NODE_ENV === 'development') {
  logger.setLogLevel(LogLevel.debug);
}

Custom Transport

import { createLogger } from './logger/logger.mjs';

const customTransport = ({ level, message, timestamp, module }) => {
  // Send to external logging service
  externalLogger.log({
    severity: level,
    message,
    timestamp,
    module,
  });
};

const logger = createLogger(customTransport);

Default Logger Instance

The default export is a pre-configured console logger:

import logger from './logger/index.mjs';

// Equivalent to:
// import { Logger } from './logger/index.mjs';
// const logger = Logger('console');

Source: logger/index.mjs:27

Related APIs

• Generator API - Uses logger for execution tracking
• Configuration API - No direct logging, but used with generators