smartlog/readme.hints.md

SmartLog - Development Hints & Notes

This document contains notes and findings about the SmartLog library to help with development and understanding of the codebase.

Key Components

• Smartlog: Main logger class that handles logging operations
• LogRouter: Routes logs to various destinations
• LogGroup: Groups related logs for better traceability
• ConsoleLog: Destination that logs to the console
• ILogDestination: Interface for implementing custom log destinations

Core Concepts

• Log Context: Metadata about the environment (company, environment, runtime, etc.)
• Log Levels: 'silly', 'info', 'debug', 'note', 'ok', 'success', 'warn', 'error', 'lifecycle'
• Log Types: 'log', 'increment', 'gauge', 'error', 'success', 'value', 'finance', 'compliance'
• Log Correlation: Used to link related logs together (group, transaction, instance)

Interactive Console Features

• SmartlogSourceInteractive: Creates interactive spinners for CLI applications
• SmartlogProgressBar: Creates progress bars for CLI applications
• Both automatically detect non-interactive environments and provide fallback behavior

Environment Detection

The library uses feature detection to adapt to different environments:

• Checks for TTY capability
• Detects CI/CD environments (GitHub Actions, Jenkins, GitLab CI, Travis, CircleCI)
• Provides appropriate output based on the environment

Available Destinations

• Console (built-in)
• File (ts_destination_file) — uses native Node fs (no longer depends on @push.rocks/smartfile)
• Local (ts_destination_local)
• Clickhouse (ts_destination_clickhouse)
• Developer Tools (ts_destination_devtools)
• Receiver (ts_destination_receiver)
• Buffer (ts_destination_buffer) — in-memory circular buffer with query/filter/pagination

Build & TS Config Notes

• tsconfig.json requires "types": ["node"] for Node globals (Buffer, process, NodeJS namespace) to be picked up by tsbuild 4.4+ / TypeScript 6.x. Without it, transitive deps like @tsclass/tsclass and @push.rocks/smartrx fail to compile because they reference Node types in their public .d.ts.
• Do NOT add baseUrl or paths: {} — baseUrl is deprecated in TS 6.x and triggers TS5101.
• Configuration is now in .smartconfig.json (renamed from npmextra.json in tsbuild 4.4).

Advanced Features

• Increment Logging: For metrics and counters
• Console Capture: Option to capture all console output through Smartlog
• Custom Destinations: Extend with custom log destinations

Tests

Test files are organized by environment compatibility:

• *.both.ts: Tests for both browser and Node.js
• *.node.ts: Tests for Node.js only
• *.browser.ts: Tests for browser only