@cheatron/log

Advanced Winston-based logging library for the Cheatron ecosystem. Featuring a shared static logger system that allows multiple packages to share the same configuration and log output.

Features

• Shared Static Logger — Configure once in your main app, use everywhere via createLogHelper.
• Scoped Logging — Automatically prefix log categories with a title (e.g. Native/Process).
• 6 Log Levels — fatal, error, warn, info, debug, trace.
• Colored Console — Pretty formatted output with colors per level.
• JSONL File Logging — Structured JSON Lines format, one object per line.
• Daily Rotation — Auto-rotating log files with configurable retention.
• Child Loggers — Scoped category loggers for modules.

Installation

bun add @cheatron/log

Usage

1. Configure once (Main App)

import { configureLogger } from '@cheatron/log';

configureLogger({
  level: 'debug',
  logsDir: './logs',
  dailyRotation: true,
});

2. Create Scoped Helpers (Packages/Modules)

Use createLogHelper to create a logger instance that automatically prefixes all categories with a title. All helpers share the same underlying global logger instance.

// in @cheatron/cheatron-native
import { createLogHelper } from '@cheatron/log';

const log = createLogHelper('Native');

log.info('App', 'Module started'); // category: Native/App

Basic Logger (Manual Instance)

If you need a standalone logger instance that doesn't share the global state:

import { createLogger } from '@cheatron/log';

const { helpers: log } = createLogger({ level: 'info' });
log.info('App', 'Standalone log');

Log Levels

| Level | Color | Use Case | | ------- | --------- | ------------------------------ | | fatal | 🔴 Red BG | Unrecoverable system failures | | error | 🔴 Red | Errors requiring attention | | warn | 🟡 Yellow | Warnings, degraded performance | | info | 🔵 Cyan | General information | | debug | ⚪ Gray | Development details | | trace | 🪨 Dim | Low-level internal tracing |

API Reference

Global Singleton API

• configureLogger(opts): Reconfigures the global shared logger instance.
• createLogHelper(title): Returns a LoggerHelpers instance that prefixes categories with title/.
• getLogger(): Returns the global LoggerHelpers.
• getWinstonLogger(): Returns the underlying Winston instance.
• getLogFilePath(): Returns current log file path (if enabled).

createLogger(opts?) Options

| Option | Type | Default | Description | | --------------- | ---------- | --------- | -------------------------- | | level | LogLevel | 'debug' | Minimum log level | | logsDir | string | — | Directory for log files | | logFileName | string | auto | Log file name | | dailyRotation | boolean | false | Enable daily file rotation | | maxFiles | string | '30d' | Retention period |

LoggerHelpers

log.fatal(category, message, data?)
log.error(category, message, data?)
log.warn(category, message, data?)
log.info(category, message, data?)
log.debug(category, message, data?)
log.trace(category, message, data?)
log.child(category) // Returns ChildLogger

License

MIT