Skip to main content

​
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:

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us