@pawells/logger

Structured logging library for TypeScript/Node.js with ESM, no runtime dependencies, and support for multiple transports and formatters for structured logging and log aggregation.

Features

• Structured logging with configurable log levels (DEBUG, INFO, WARN, ERROR, FATAL)
• Multiple built-in transports: Console (with ANSI colors)
• Pluggable transport system for custom integrations
• JSON formatter for log aggregation platforms
• Nanosecond-precision timestamps
• Support for metadata and tracing fields (traceId, spanId, correlationId)
• Full TypeScript support with strict typing
• ESM-only, no runtime dependencies
• Targets ES2022, runs on Node.js >= 24.0.0

Installation

npm install @pawells/logger
# or
yarn add @pawells/logger

Quick Start

import { Logger, ConsoleTransport, LogLevel } from '@pawells/logger';

// Create a logger instance
const logger = new Logger({
  service: 'my-app',
  level: LogLevel.DEBUG,
  transport: new ConsoleTransport(),
});

// Log messages at different levels
await logger.debug('Debug information', { userId: 123 });
await logger.info('Application started');
await logger.warn('Memory usage is high', { usage: 85 });
await logger.error('Request failed', { statusCode: 500 });
await logger.fatal('System critical error', { errno: 'EACCES' });

API Reference

Logger Class

Main logging interface with methods for each log level.

Constructor

constructor(config: ILoggerConfig)

ILoggerConfig:

• service: string — Required service name for the logger
• level?: LogLevel — Minimum log level to output (defaults to INFO)
• format?: 'json' | 'text' — Output format (defaults to 'text')
• transport?: ITransport — Transport to send logs to (defaults to ConsoleTransport)

Methods

async debug(message: string, metadata?: Record<string, unknown>): Promise<void>
async info(message: string, metadata?: Record<string, unknown>): Promise<void>
async warn(message: string, metadata?: Record<string, unknown>): Promise<void>
async error(message: string, metadata?: Record<string, unknown>): Promise<void>
async fatal(message: string, metadata?: Record<string, unknown>): Promise<void>

LogLevel Enum

enum LogLevel {
  DEBUG = 'debug',
  INFO = 'info',
  WARN = 'warn',
  ERROR = 'error',
  FATAL = 'fatal',
}

ConsoleTransport

Outputs log entries to the console with ANSI color formatting.

import { ConsoleTransport, LogLevel } from '@pawells/logger';

const transport = new ConsoleTransport({ service: 'my-app', level: LogLevel.INFO });
const logger = new Logger({
  service: 'my-app',
  level: LogLevel.INFO,
  transport: transport,
});

formatForJson()

Formats log entries as structured JSON compatible with log aggregation platforms.

import { formatForJson, ILogEntry, LogLevel } from '@pawells/logger';

const logEntry: ILogEntry = {
  timestamp: Date.now().toString(),
  level: LogLevel.INFO,
  service: 'my-app',
  message: 'User login successful',
  metadata: { userId: '42' },
};

const jsonOutput = formatForJson(logEntry);
// Output: {"timestamp":"1705257983000000000","level":"info","service":"my-app","message":"User login successful","metadata":{"userId":"42"}}

ITransport Interface

Implement this interface to create custom transports.

interface ITransport {
  write(entry: ILogEntry): void | Promise<void>;
}

ILogEntry:

• timestamp: string — Nanosecond-precision timestamp as string
• level: LogLevel — Log level
• service: string — Service name
• message: string — Log message
• metadata?: Record<string, unknown> — Contextual metadata
• traceId?: string — Distributed trace ID
• spanId?: string — Distributed span ID
• correlationId?: string — Correlation ID for request tracking

Custom Transport Example

Create a custom transport to send logs to an external service:

import { Logger, ITransport, ILogEntry, LogLevel } from '@pawells/logger';

class FileTransport implements ITransport {
  constructor(private filePath: string) {}

  async write(entry: ILogEntry): Promise<void> {
    const line = `[${entry.level}] ${entry.message}\n`;
    // Write to file (implementation varies by use case)
    await appendToFile(this.filePath, line);
  }
}

const logger = new Logger({
  service: 'my-app',
  level: LogLevel.INFO,
  transport: new FileTransport('./logs/app.log'),
});

Log Aggregation Integration

For log aggregation with external platforms:

import { Logger, ITransport, ILogEntry, formatForJson, LogLevel } from '@pawells/logger';

class AggregationTransport implements ITransport {
  constructor(private endpoint: string) {}

  async write(entry: ILogEntry): Promise<void> {
    const jsonOutput = formatForJson(entry);
    await fetch(this.endpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: jsonOutput,
    });
  }
}

const logger = new Logger({
  service: 'my-app',
  level: LogLevel.DEBUG,
  transport: new AggregationTransport('https://aggregation.example.com/api/v1/push'),
});

TypeScript Support

Full TypeScript support with strict typing. All types are exported for custom implementations:

import {
  Logger,
  LogLevel,
  ILogEntry,
  ILoggerConfig,
  ITransport,
  ConsoleTransport,
  formatForJson,
} from '@pawells/logger';

Development

yarn install        # Install dependencies
yarn build          # Compile TypeScript (tsconfig.build.json) → ./build/
yarn dev            # Build + run
yarn watch          # Watch mode
yarn typecheck      # Type check without building
yarn lint           # ESLint
yarn lint:fix       # ESLint with auto-fix
yarn test           # Run tests
yarn test:ui        # Interactive Vitest UI
yarn test:coverage  # Tests with coverage report

Requirements

• Node.js >= 24.0.0

License

MIT — See LICENSE for details.