3.1.9

API.md

@@ -0,0 +1,300 @@
+# @push.rocks/smartlog API Reference
+
+This document provides a detailed reference for all exports and APIs available in the @push.rocks/smartlog package and its submodules.
+
+## Core Module (`@push.rocks/smartlog`)
+
+The core module provides the main logging functionality.
+
+### Classes
+
+#### `Smartlog`
+
+Main logger class for creating, managing, and routing logs.
+
+```typescript
+import { Smartlog } from '@push.rocks/smartlog';
+
+const logger = new Smartlog({
+  logContext: {
+    company: 'MyCompany',
+    environment: 'production',
+    // ...other context properties
+  },
+  minimumLogLevel: 'info' // Optional, defaults to 'silly'
+});
+```
+
+**Constructor Options:**
+- `logContext`: Object containing context information about the environment
+- `minimumLogLevel`: Optional minimum log level to process (defaults to 'silly')
+
+**Methods:**
+- `log(logLevel, message, data?, correlation?)`: Log a message with optional data and correlation
+- `increment(logLevel, message, data?, correlation?)`: Log an increment counter
+- `addLogDestination(destination)`: Add a custom log destination
+- `enableConsole(options?)`: Enable console logging (with optional stdout/stderr capture)
+- `createLogGroup(transactionId?)`: Create a log group for related logs
+- `handleLog(logPackage)`: Handle a pre-formatted log package
+
+**Static Methods:**
+- `createForCommitinfo(commitinfo)`: Create a logger with commit information
+
+#### `LogGroup`
+
+Groups related logs together for better traceability.
+
+```typescript
+import { Smartlog } from '@push.rocks/smartlog';
+
+const logger = new Smartlog({/*...*/});
+const logGroup = logger.createLogGroup('transaction-123');
+
+logGroup.log('info', 'Starting process');
+// All logs in this group will share the same transaction ID
+```
+
+**Methods:**
+- `log(logLevel, message, data?)`: Log a message within this group
+- `increment(logLevel, message, data?)`: Log an increment within this group
+
+#### `ConsoleLog`
+
+Implementation of `ILogDestination` that logs to console.
+
+## Interfaces Module (`@push.rocks/smartlog/interfaces`)
+
+This module provides all type definitions and interfaces used by Smartlog.
+
+### Types
+
+- `TLogType`: Available log types
+  - `'log' | 'increment' | 'gauge' | 'error' | 'success' | 'value' | 'finance' | 'compliance'`
+
+- `TLogLevel`: Available log levels
+  - `'silly' | 'info' | 'debug' | 'note' | 'ok' | 'success' | 'warn' | 'error' | 'lifecycle'`
+
+- `TEnvironment`: Available environments
+  - `'local' | 'test' | 'staging' | 'production'`
+
+- `TRuntime`: Available runtime environments
+  - `'node' | 'chrome' | 'rust' | 'deno' | 'cloudflare_workers'`
+
+### Interfaces
+
+#### `ILogContext`
+
+Metadata about the environment where logging occurs.
+
+```typescript
+interface ILogContext {
+  commitinfo?: ICommitInfo;
+  company?: string;
+  companyunit?: string;
+  containerName?: string;
+  environment?: TEnvironment;
+  runtime?: TRuntime;
+  zone?: string;
+}
+```
+
+#### `ILogCorrelation`
+
+Information for correlating related logs.
+
+```typescript
+interface ILogCorrelation {
+  id: string;
+  type: 'none' | 'service' | 'build' | 'infrastructure' | 'cdn';
+  instance?: string;
+  group?: string;
+  transaction?: string;
+}
+```
+
+#### `ILogPackage<T = unknown>`
+
+The standard log package format.
+
+```typescript
+interface ILogPackage<T = unknown> {
+  timestamp: number;
+  type: TLogType;
+  context: ILogContext;
+  level: TLogLevel;
+  correlation: ILogCorrelation;
+  message: string;
+  data?: T;
+}
+```
+
+#### `ILogDestination`
+
+Interface for implementing custom log destinations.
+
+```typescript
+interface ILogDestination {
+  handleLog: (logPackage: ILogPackage) => Promise<void>;
+}
+```
+
+## Interactive Console Module (`@push.rocks/smartlog/source-interactive`)
+
+This module provides interactive console components like spinners and progress bars.
+
+### Classes
+
+#### `SmartlogSourceInteractive`
+
+Creates interactive spinners for CLI applications.
+
+```typescript
+import { SmartlogSourceInteractive } from '@push.rocks/smartlog/source-interactive';
+
+const spinner = new SmartlogSourceInteractive();
+spinner.text('Loading data...');
+// Later
+spinner.finishSuccess('Data loaded successfully!');
+```
+
+**Methods:**
+- `text(message)`: Sets the spinner text and starts it if not running
+- `finishSuccess(message?)`: Completes the spinner with success message
+- `finishFail(message?)`: Completes the spinner with failure message
+- `successAndNext(message)`: Marks success and starts a new spinner
+- `failAndNext(message)`: Marks failure and starts a new spinner
+- `setSpinnerStyle(style)`: Sets spinner style ('dots', 'line', 'star', 'simple')
+- `setColor(color)`: Sets the spinner color
+- `setSpeed(ms)`: Sets the animation speed
+
+#### `SmartlogProgressBar`
+
+Creates progress bars for CLI applications.
+
+```typescript
+import { SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';
+
+const bar = new SmartlogProgressBar({
+  total: 100,
+  width: 40,
+  showEta: true
+});
+
+bar.update(50); // Update to 50%
+bar.increment(10); // Increment by 10 units
+bar.complete(); // Complete the progress bar
+```
+
+**Constructor Options:**
+- `total`: Total number of items/steps
+- `width`: Width of the bar in characters
+- `complete`: Character for completed section
+- `incomplete`: Character for incomplete section
+- `renderThrottle`: Minimum time between renders
+- `clear`: Whether to clear the bar on completion
+- `showEta`: Show estimated time remaining
+- `showPercent`: Show percentage completed
+- `showCount`: Show count of items
+
+**Methods:**
+- `update(value)`: Update progress to a specific value
+- `increment(value?)`: Increment progress by a value (default: 1)
+- `complete()`: Mark the progress bar as complete
+- `setColor(color)`: Set the color of the progress bar
+
+## File Destination Module (`@push.rocks/smartlog/destination-file`)
+
+This module provides a log destination that writes logs to a file.
+
+### Classes
+
+#### `SmartlogDestinationFile`
+
+Writes logs to a file with timestamps.
+
+```typescript
+import { Smartlog } from '@push.rocks/smartlog';
+import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';
+
+const logger = new Smartlog({/*...*/});
+const fileDestination = new SmartlogDestinationFile('/absolute/path/to/logfile.log');
+logger.addLogDestination(fileDestination);
+```
+
+**Constructor Parameters:**
+- `filePath`: Absolute path to the log file
+
+## Local Destination Module (`@push.rocks/smartlog/destination-local`)
+
+This module provides a log destination with colorful formatting for local development.
+
+### Classes
+
+#### `DestinationLocal`
+
+Formats logs with colors and prefixes for better readability in the console.
+
+```typescript
+import { Smartlog } from '@push.rocks/smartlog';
+import { DestinationLocal } from '@push.rocks/smartlog/destination-local';
+
+const logger = new Smartlog({/*...*/});
+const localDestination = new DestinationLocal();
+logger.addLogDestination(localDestination);
+```
+
+**Methods:**
+- `handleLog(logPackage)`: Handles a log package
+- `newLine(lines?)`: Adds empty lines to the console
+- `logReduced(text, repeatEveryTimes?)`: Logs only when the message changes
+
+## DevTools Destination Module (`@push.rocks/smartlog/destination-devtools`)
+
+This module provides a log destination that formats logs for browser developer tools.
+
+### Classes
+
+#### `SmartlogDestinationDevtools`
+
+Formats logs with colors for browser developer tools.
+
+```typescript
+import { Smartlog } from '@push.rocks/smartlog';
+import { SmartlogDestinationDevtools } from '@push.rocks/smartlog/destination-devtools';
+
+const logger = new Smartlog({/*...*/});
+const devtoolsDestination = new SmartlogDestinationDevtools();
+logger.addLogDestination(devtoolsDestination);
+```
+
+## ClickHouse Destination Module (`@push.rocks/smartlog/destination-clickhouse`)
+
+This module provides a log destination that stores logs in a ClickHouse database.
+
+### Classes
+
+#### `SmartlogDestinationClickhouse`
+
+Stores logs in a ClickHouse database for analytics and querying.
+
+```typescript
+import { Smartlog } from '@push.rocks/smartlog';
+import { SmartlogDestinationClickhouse } from '@push.rocks/smartlog/destination-clickhouse';
+
+const logger = new Smartlog({/*...*/});
+const clickhouseDestination = await SmartlogDestinationClickhouse.createAndStart({
+  host: 'clickhouse.example.com',
+  port: 8123,
+  user: 'username',
+  password: 'password',
+  database: 'logs_db'
+});
+logger.addLogDestination(clickhouseDestination);
+```
+
+**Static Methods:**
+- `createAndStart(options)`: Create and initialize a ClickHouse destination
+
+**Methods:**
+- `start()`: Initialize the connection to ClickHouse
+- `handleLog(logPackage)`: Store a log in ClickHouse

changelog.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 2025-09-01 - 3.1.9 - fix(docs)
+Update README: expand documentation, examples and usage guides
+
+- Fully rewrote README to a comprehensive documentation page with badges, motivation and feature overview.
+- Added Quick Start, detailed usage examples and code snippets for Smartlog, destinations, and custom destinations.
+- Documented interactive console features (spinners, progress bars) including non-interactive fallbacks and configuration options.
+- Expanded sections on built-in destinations (console, file, devtools, ClickHouse, receiver) with practical examples and env-driven configuration.
+- Added integration examples (PM2, Docker), CLI usage, advanced features (context management, scoped logging, minimum log levels) and best practices.
+- Included API reference pointers and contributing / license information.
+
+## 2025-05-20 - 3.1.8 - fix(devDependencies)
+Update devDependencies for tstest and Node types
+
+- Bump @git.zone/tstest from ^1.7.0 to ^1.9.0
+- Bump @types/node from ^22.15.18 to ^22.15.20
+
+## 2025-05-20 - 3.1.7 - fix(ts_destination_local)
+Update debug log color: set textColor to 'pink' in DestinationLocal.
+
+- Changed debug log text color from 'gray' to 'pink' for improved consistency in log output
+
+## 2025-05-20 - 3.1.6 - fix(ts_destination_local)
+Update debug prefix color in DestinationLocal: change from gray to pink for improved visibility.
+
+- Adjusted the 'debug' log prefix color in classes.destinationlocal.ts to use 'pink' instead of 'gray'.
+
+## 2025-05-20 - 3.1.5 - fix(core)
+Maintain and verify project metadata and commit info consistency
+
+- No code changes; confirming commit info files and documentation remain aligned
+- Ensured consistent versioning across submodules and package metadata
+
+## 2025-05-20 - 3.1.4 - fix(DestinationLocal)
+Fix debug log rendering, add fallback for unknown log levels, and correct error prefix typo in local destination
+
+- Added tests for debug and unknown log levels in DestinationLocal
+- Refactored log string generation to use a fallback style for undefined levels
+- Fixed typo: replaced non-existent 'errorPrefix' with 'error.prefix'
+
+## 2025-05-19 - 3.1.3 - fix(documentation)
+Update API reference and enhance README with detailed examples and usage instructions
+
+- Added comprehensive API.md with reference details for core modules, interfaces, and interactive console features
+- Updated README.md with improved installation steps, usage examples, and log group information
+- Revised development hints to reflect environment detection and test file organization
+
 ## 2025-05-16 - 3.1.2 - fix(tests)
 Update test imports and devDependencies to use @git.zone/tstest/tapbundle
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartlog",
-  "version": "3.1.2",
+  "version": "3.1.9",
   "private": false,
   "description": "A minimalistic, distributed, and extensible logging tool supporting centralized log management.",
   "keywords": [
@@ -45,8 +45,8 @@
     "@git.zone/tsbuild": "^2.5.1",
     "@git.zone/tsbundle": "^2.2.5",
     "@git.zone/tsrun": "^1.3.3",
-    "@git.zone/tstest": "^1.7.0",
-    "@types/node": "^22.15.18"
+    "@git.zone/tstest": "^1.9.0",
+    "@types/node": "^22.15.20"
   },
   "dependencies": {
     "@api.global/typedrequest-interfaces": "^3.0.19",

readme.hints.md

@@ -1 +1,53 @@
- 
+# 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)
+- Local (ts_destination_local) 
+- Clickhouse (ts_destination_clickhouse)
+- Developer Tools (ts_destination_devtools)
+- Receiver (ts_destination_receiver)
+
+## 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

readme.md

@@ -1,184 +1,736 @@
-# @push.rocks/smartlog
+# @push.rocks/smartlog 🚀
+*The ultimate TypeScript logging solution for modern applications*
 
-minimalistic distributed and extensible logging tool
+[![npm version](https://img.shields.io/npm/v/@push.rocks/smartlog.svg)](https://www.npmjs.com/package/@push.rocks/smartlog)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Install
+> **smartlog** is a powerful, distributed, and extensible logging system designed for the cloud-native era. Whether you're debugging locally, monitoring production systems, or building complex microservices, smartlog adapts to your needs with style. 🎯
 
-You can install `@push.rocks/smartlog` using npm:
+## 🌟 Why smartlog?
 
-```sh
-npm install @push.rocks/smartlog --save
+- **🎨 Beautiful Console Output**: Color-coded, formatted logs that are actually readable
+- **🔌 Extensible Architecture**: Plug in any destination - databases, files, remote servers
+- **🌍 Distributed by Design**: Built for microservices with correlation and context tracking
+- **⚡ Zero-Config Start**: Works out of the box, scales when you need it
+- **🎭 Interactive CLI Tools**: Spinners and progress bars that handle non-TTY environments gracefully
+- **📊 Structured Logging**: JSON-based for easy parsing and analysis
+- **🔍 Smart Filtering**: Log levels and context-based filtering
+
+## 📦 Installation
+
+```bash
+# Using pnpm (recommended)
+pnpm add @push.rocks/smartlog
+
+# Using npm
+npm install @push.rocks/smartlog
+
+# Using yarn
+yarn add @push.rocks/smartlog
 ```
 
-Ensure that you have TypeScript and node.js installed in your development environment, as this module is intended to be used with TypeScript.
+## 🚀 Quick Start
 
-## Usage
-
-`@push.rocks/smartlog` is a flexible and extensible logging tool designed to provide a minimalistic yet powerful logging solution across different environments, making it especially useful in distributed systems. This documentation aims to guide you through its capabilities, setup, and how to integrate it seamlessly into your TypeScript projects.
-
-### Creating a Logger Instance
-
-Start by importing `Smartlog` and create a logger instance by providing a context that describes your logging environment:
+### Your First Logger
 
 ```typescript
 import { Smartlog } from '@push.rocks/smartlog';
 
+// Create a logger with context
 const logger = new Smartlog({
   logContext: {
-    company: 'My awesome company',
-    companyunit: 'my awesome cloud team',
-    containerName: 'awesome-container',
-    environment: 'kubernetes-production',
+    company: 'MyStartup',
+    companyunit: 'Backend Team',
+    containerName: 'api-gateway',
+    environment: 'production',
     runtime: 'node',
-    zone: 'zone x',
-  },
+    zone: 'eu-central'
+  }
+});
+
+// Enable beautiful console output
+logger.enableConsole();
+
+// Start logging!
+logger.log('info', '🎉 Application started successfully');
+logger.log('error', '💥 Database connection failed', { 
+  errorCode: 'DB_TIMEOUT',
+  attemptCount: 3 
 });
 ```
 
-This context enriches your logs with valuable information, making them easier to filter and analyze in a distributed system.
-
-### Logging Messages
-
-Logging is straightforward; you can log messages at various levels such as `info`, `warn`, `error`, `silly`, etc.:
-
-```typescript
-logger.log('info', 'This is an info message');
-logger.log('error', 'This is an error message with details', { errorCode: 123 });
-```
-
-The logging method accepts additional data as the third parameter, allowing you to attach more context to each log message, which is immensely useful for debugging.
-
 ### Using the Default Logger
 
-For convenience, `@push.rocks/smartlog` provides a default logger that you can use out of the box:
+For quick prototyping and simple applications:
 
 ```typescript
 import { defaultLogger } from '@push.rocks/smartlog';
 
-defaultLogger.log('warn', 'This is a warning message using the default logger');
+defaultLogger.log('info', 'This is so easy!');
 ```
 
-This is particularly helpful for simple applications or for initial project setup.
+## 📚 Core Concepts
 
-### Interactive Console Features
+### Log Levels
 
-Smartlog provides interactive console features through the `@push.rocks/smartlog/source-interactive` module:
+smartlog supports semantic log levels for different scenarios:
 
-#### Spinners
+```typescript
+// Lifecycle events
+logger.log('lifecycle', '🔄 Container starting up...');
 
-Use spinners to show progress for operations:
+// Success states
+logger.log('success', '✅ Payment processed');
+logger.log('ok', '👍 Health check passed');
+
+// Information and debugging
+logger.log('info', '📋 User profile updated');
+logger.log('note', '📌 Cache invalidated');
+logger.log('debug', '🔍 Query execution plan', { sql: 'SELECT * FROM users' });
+
+// Warnings and errors
+logger.log('warn', '⚠️  Memory usage above 80%');
+logger.log('error', '❌ Failed to send email');
+
+// Verbose output
+logger.log('silly', '🔬 Entering function processPayment()');
+```
+
+### Log Groups for Correlation
+
+Perfect for tracking request flows through your system:
+
+```typescript
+// Track a user request through multiple operations
+const requestGroup = logger.createLogGroup('req-7f3a2b');
+
+requestGroup.log('info', 'Received POST /api/users');
+requestGroup.log('debug', 'Validating request body');
+requestGroup.log('info', 'Creating user in database');
+requestGroup.log('success', 'User created successfully', { userId: 'usr_123' });
+
+// All logs in the group share the same correlation ID
+```
+
+## 🎯 Log Destinations
+
+### Built-in Destinations
+
+#### 🖥️ Local Console (Enhanced)
+
+Beautiful, colored output for local development:
+
+```typescript
+import { DestinationLocal } from '@push.rocks/smartlog/destination-local';
+
+const localDestination = new DestinationLocal({
+  logLevel: 'debug'  // Optional: filter by minimum log level
+});
+
+logger.addLogDestination(localDestination);
+```
+
+#### 📁 File Logging
+
+Persist logs to files with automatic rotation support:
+
+```typescript
+import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';
+
+const fileDestination = new SmartlogDestinationFile('./logs/app.log');
+logger.addLogDestination(fileDestination);
+```
+
+#### 🌐 Browser DevTools
+
+Optimized for browser environments with styled console output:
+
+```typescript
+import { SmartlogDestinationDevtools } from '@push.rocks/smartlog/destination-devtools';
+
+const devtools = new SmartlogDestinationDevtools();
+logger.addLogDestination(devtools);
+```
+
+#### 📊 ClickHouse Analytics
+
+Store logs in ClickHouse for powerful analytics:
+
+```typescript
+import { SmartlogDestinationClickhouse } from '@push.rocks/smartlog/destination-clickhouse';
+
+const clickhouse = await SmartlogDestinationClickhouse.createAndStart({
+  host: 'analytics.example.com',
+  port: 8123,
+  database: 'logs',
+  user: 'logger',
+  password: process.env.CLICKHOUSE_PASSWORD
+});
+
+logger.addLogDestination(clickhouse);
+
+// Query your logs with SQL!
+// SELECT * FROM logs WHERE level = 'error' AND timestamp > now() - INTERVAL 1 HOUR
+```
+
+#### 🔗 Remote Receiver
+
+Send logs to a centralized logging service:
+
+```typescript
+import { SmartlogDestinationReceiver } from '@push.rocks/smartlog/destination-receiver';
+
+const receiver = new SmartlogDestinationReceiver({
+  endpoint: 'https://logs.mycompany.com/ingest',
+  apiKey: process.env.LOG_API_KEY,
+  batchSize: 100,  // Send logs in batches
+  flushInterval: 5000  // Flush every 5 seconds
+});
+
+logger.addLogDestination(receiver);
+```
+
+### 🛠️ Custom Destinations
+
+Build your own destination for any logging backend:
+
+```typescript
+import { ILogDestination, ILogPackage } from '@push.rocks/smartlog/interfaces';
+
+class ElasticsearchDestination implements ILogDestination {
+  private client: ElasticsearchClient;
+
+  constructor(config: ElasticsearchConfig) {
+    this.client = new ElasticsearchClient(config);
+  }
+
+  async handleLog(logPackage: ILogPackage): Promise<void> {
+    await this.client.index({
+      index: `logs-${new Date().toISOString().split('T')[0]}`,
+      body: {
+        '@timestamp': logPackage.timestamp,
+        level: logPackage.level,
+        message: logPackage.message,
+        context: logPackage.context,
+        data: logPackage.data,
+        correlation: logPackage.correlation
+      }
+    });
+  }
+}
+
+// Use your custom destination
+logger.addLogDestination(new ElasticsearchDestination({
+  node: 'https://elasticsearch.example.com'
+}));
+```
+
+## 🎨 Interactive Console Features
+
+### Spinners
+
+Create beautiful loading animations that degrade gracefully in CI/CD:
 
 ```typescript
 import { SmartlogSourceInteractive } from '@push.rocks/smartlog/source-interactive';
 
 const spinner = new SmartlogSourceInteractive();
-spinner.text('Loading data...');
 
-// Later, when the operation completes:
-spinner.finishSuccess('Data loaded successfully!');
-// Or if it fails:
-spinner.finishFail('Failed to load data');
+// Basic usage
+spinner.text('🔄 Fetching data from API...');
+// ... perform async operation
+spinner.finishSuccess('✅ Data fetched successfully!');
 
-// You can chain operations:
-spinner.text('Connecting to server');
-spinner.successAndNext('Fetching records');
-spinner.successAndNext('Processing data');
-spinner.finishSuccess('All done!');
+// Chained operations
+spinner
+  .text('📡 Connecting to database')
+  .successAndNext('🔍 Running migrations')
+  .successAndNext('🌱 Seeding data')
+  .finishSuccess('🎉 Database ready!');
 
-// Customize appearance:
-spinner.setSpinnerStyle('line'); // 'dots', 'line', 'star', or 'simple'
-spinner.setColor('green');       // 'red', 'green', 'yellow', 'blue', etc.
-spinner.setSpeed(100);           // Animation speed in milliseconds
+// Customize appearance
+spinner
+  .setSpinnerStyle('dots')  // dots, line, star, simple
+  .setColor('cyan')         // any terminal color
+  .setSpeed(80)            // animation speed in ms
+  .text('🚀 Deploying application...');
+
+// Handle failures
+try {
+  await deployApp();
+  spinner.finishSuccess('✅ Deployed!');
+} catch (error) {
+  spinner.finishFail('❌ Deployment failed');
+}
 ```
 
-#### Progress Bars
+### Progress Bars
 
-Create progress bars for tracking operation progress:
+Track long-running operations with style:
 
 ```typescript
 import { SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';
 
-const progressBar = new SmartlogProgressBar({
-  total: 100,                // Total number of items
-  width: 40,                 // Width of the progress bar
-  complete: '█',             // Character for completed section
-  incomplete: '░',           // Character for incomplete section
-  showEta: true,             // Show estimated time remaining
-  showPercent: true,         // Show percentage
-  showCount: true            // Show count (e.g., "50/100")
+// Create a progress bar
+const progress = new SmartlogProgressBar({
+  total: 100,
+  width: 40,
+  complete: '█',
+  incomplete: '░',
+  showEta: true,
+  showPercent: true,
+  showCount: true
 });
 
 // Update progress
-progressBar.update(50);      // Set to 50% progress
+for (let i = 0; i <= 100; i++) {
+  progress.update(i);
+  await someAsyncWork();
+}
 
-// Or increment
-progressBar.increment(10);   // Increase by 10 units
+progress.complete();
 
-// Change color
-progressBar.setColor('blue');
+// Real-world example: Processing files
+const files = await getFiles();
+const progress = new SmartlogProgressBar({
+  total: files.length,
+  width: 50
+});
 
-// Complete the progress bar
-progressBar.update(100);     // or progressBar.complete();
+for (const [index, file] of files.entries()) {
+  await processFile(file);
+  progress.increment();  // or progress.update(index + 1)
+}
 ```
 
-#### Non-Interactive Environments
+### Non-Interactive Fallback
 
-Both spinners and progress bars automatically detect non-interactive environments (CI/CD, piped output, non-TTY) and provide fallback text-based output:
+Both spinners and progress bars automatically detect non-interactive environments (CI/CD, Docker logs, piped output) and fallback to simple text output:
 
 ```
-[Loading] Loading data...
+[Loading] Connecting to database
+[Success] Connected to database
+[Loading] Running migrations
+Progress: 25% (25/100)
 Progress: 50% (50/100)
 Progress: 100% (100/100)
-[Success] Data loaded successfully!
+[Success] Migrations complete
 ```
 
-### Extending With Log Destinations
+## 🔧 Advanced Features
 
-One of the core strengths of `@push.rocks/smartlog` is its ability to work with multiple log destinations, enabling you to log messages not just to the console but also to external logging services or custom destinations.
+### Context Management
 
-To add a log destination, you create a class that implements the `ILogDestination` interface and then add it to the logger:
+Add context that flows through your entire application:
 
 ```typescript
-import { Smartlog, ILogDestination } from '@push.rocks/smartlog';
+// Set global context
+logger.addLogContext({
+  requestId: 'req-123',
+  userId: 'user-456',
+  feature: 'payment-processing'
+});
 
-class MyCustomLogDestination implements ILogDestination {
-  async handleLog(logPackage) {
-    // Implement your custom logging logic here
-    console.log(`Custom log: ${logPackage.message}`);
+// All subsequent logs include this context
+logger.log('info', 'Processing payment');
+// Output includes: { ...context, message: 'Processing payment' }
+```
+
+### Scoped Logging
+
+Create scoped loggers for different components:
+
+```typescript
+const dbLogger = logger.createScope('database');
+const apiLogger = logger.createScope('api');
+
+dbLogger.log('info', 'Executing query');
+apiLogger.log('info', 'Handling request');
+// Logs include scope information for filtering
+```
+
+### Minimum Log Levels
+
+Control log verbosity per environment:
+
+```typescript
+const logger = new Smartlog({
+  logContext: { environment: 'production' },
+  minimumLogLevel: 'warn'  // Only warn and above in production
+});
+
+// These won't be logged in production
+logger.log('debug', 'Detailed debug info');
+logger.log('info', 'Regular info');
+
+// These will be logged
+logger.log('warn', 'Warning message');
+logger.log('error', 'Error message');
+```
+
+### Increment Logging
+
+Perfect for metrics and counters:
+
+```typescript
+// Track API calls
+logger.increment('info', 'api.requests', { endpoint: '/users', method: 'GET' });
+logger.increment('info', 'api.requests', { endpoint: '/users', method: 'POST' });
+
+// Track errors by type
+logger.increment('error', 'payment.failed', { reason: 'insufficient_funds' });
+logger.increment('error', 'payment.failed', { reason: 'card_declined' });
+```
+
+### Capture All Console Output
+
+Redirect all console.log and console.error through smartlog:
+
+```typescript
+logger.enableConsole({ 
+  captureAll: true  // Capture all console.* methods
+});
+
+console.log('This goes through smartlog!');
+console.error('This too!');
+// All console output is now structured and routed through your destinations
+```
+
+## 🏗️ Real-World Examples
+
+### Microservice with Distributed Tracing
+
+```typescript
+import { Smartlog } from '@push.rocks/smartlog';
+import { SmartlogDestinationClickhouse } from '@push.rocks/smartlog/destination-clickhouse';
+
+// Initialize logger with service context
+const logger = new Smartlog({
+  logContext: {
+    company: 'TechCorp',
+    companyunit: 'Platform',
+    containerName: 'user-service',
+    environment: process.env.NODE_ENV,
+    runtime: 'node',
+    zone: process.env.CLOUD_ZONE
   }
+});
+
+// Add ClickHouse for analytics
+const clickhouse = await SmartlogDestinationClickhouse.createAndStart({
+  host: process.env.CLICKHOUSE_HOST,
+  database: 'microservices_logs'
+});
+logger.addLogDestination(clickhouse);
+
+// Enable local console for development
+if (process.env.NODE_ENV === 'development') {
+  logger.enableConsole();
 }
 
+// Express middleware for request tracking
+app.use((req, res, next) => {
+  const requestId = generateRequestId();
+  const logGroup = logger.createLogGroup(requestId);
+  
+  // Attach logger to request
+  req.logger = logGroup;
+  
+  // Log request
+  logGroup.log('info', 'Incoming request', {
+    method: req.method,
+    path: req.path,
+    ip: req.ip
+  });
+  
+  // Track response
+  res.on('finish', () => {
+    logGroup.log('info', 'Request completed', {
+      statusCode: res.statusCode,
+      duration: Date.now() - req.startTime
+    });
+  });
+  
+  next();
+});
+```
+
+### CLI Tool with Progress Tracking
+
+```typescript
+import { Smartlog } from '@push.rocks/smartlog';
+import { SmartlogSourceInteractive, SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';
+
 const logger = new Smartlog({
   logContext: {
-    /* your context */
-  },
+    containerName: 'migration-tool',
+    environment: 'cli'
+  }
 });
-logger.addLogDestination(new MyCustomLogDestination());
+
+logger.enableConsole();
+
+async function migrateDatabase() {
+  const spinner = new SmartlogSourceInteractive();
+  
+  // Connect to database
+  spinner.text('🔌 Connecting to database...');
+  await connectDB();
+  spinner.finishSuccess('✅ Connected to database');
+  
+  // Get migrations
+  spinner.text('📋 Loading migrations...');
+  const migrations = await getMigrations();
+  spinner.finishSuccess(`✅ Found ${migrations.length} migrations`);
+  
+  // Run migrations with progress bar
+  const progress = new SmartlogProgressBar({
+    total: migrations.length,
+    width: 40,
+    showEta: true
+  });
+  
+  for (const [index, migration] of migrations.entries()) {
+    logger.log('info', `Running migration: ${migration.name}`);
+    await runMigration(migration);
+    progress.update(index + 1);
+  }
+  
+  progress.complete();
+  logger.log('success', '🎉 All migrations completed successfully!');
+}
 ```
 
-After adding your custom log destination(s), every log message sent through `Smartlog` will also be routed to them according to their implementation.
+### Production Logging with Multiple Destinations
 
-### Integration with Logging Services
+```typescript
+import { Smartlog } from '@push.rocks/smartlog';
+import { DestinationLocal } from '@push.rocks/smartlog/destination-local';
+import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';
+import { SmartlogDestinationReceiver } from '@push.rocks/smartlog/destination-receiver';
 
-`@push.rocks/smartlog` is designed to be extensible; you can integrate it with various logging services like Scalyr, Elasticsearch, LogDNA, etc., by developing or using existing log destinations conforming to those services.
+const logger = new Smartlog({
+  logContext: {
+    company: 'Enterprise Corp',
+    containerName: 'payment-processor',
+    environment: 'production',
+    runtime: 'node',
+    zone: 'us-east-1'
+  },
+  minimumLogLevel: 'info'  // No debug logs in production
+});
 
-Check the npm registry or GitHub for community-contributed log destinations that can seamlessly integrate `@push.rocks/smartlog` into your preferred logging infrastructure.
+// Console for container logs (structured for log aggregators)
+logger.addLogDestination(new DestinationLocal());
 
-### Advanced Usage
+// File for audit trail
+logger.addLogDestination(new SmartlogDestinationFile('/var/log/app/audit.log'));
 
-- **Log Groups**: You can use log groups to associate related log messages, which is especially handy for tracking logs across distributed systems.
-- **Custom Log Levels**: Beyond the standard log levels, you can define custom log levels that suit your project needs.
-- **Dynamic Log Contexts**: The log context can be dynamically adjusted to reflect different stages or aspects of your application logic.
+// Central logging service
+logger.addLogDestination(new SmartlogDestinationReceiver({
+  endpoint: 'https://logs.enterprise.com/ingest',
+  apiKey: process.env.LOG_API_KEY,
+  batchSize: 100,
+  flushInterval: 5000
+}));
 
-### Conclusion
+// Critical error alerts
+logger.addLogDestination({
+  async handleLog(logPackage) {
+    if (logPackage.level === 'error' && logPackage.data?.critical) {
+      await sendAlert({
+        channel: 'ops-team',
+        message: `🚨 Critical error: ${logPackage.message}`,
+        data: logPackage
+      });
+    }
+  }
+});
+```
 
-`@push.rocks/smartlog` empowers you to implement a robust logging solution tailored to your needs with minimal effort. Its design promotes clarity, flexibility, and integration ease, making it an excellent choice for projects of any scale.
+## 🔌 Integration with Other Tools
 
-Remember to refer to the official documentation and the type definitions for detailed information on all available methods and configurations. Happy logging!
+### PM2 Integration
 
-## License and Legal Information
+```typescript
+// ecosystem.config.js
+module.exports = {
+  apps: [{
+    name: 'api',
+    script: './dist/index.js',
+    error_file: '/dev/null',  // Disable PM2 error log
+    out_file: '/dev/null',    // Disable PM2 out log
+    merge_logs: true,
+    env: {
+      NODE_ENV: 'production',
+      // smartlog handles all logging
+    }
+  }]
+};
+```
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
+### Docker Integration
+
+```dockerfile
+FROM node:18-alpine
+WORKDIR /app
+COPY . .
+RUN pnpm install --production
+
+# smartlog handles structured logging
+# No need for special log drivers
+CMD ["node", "dist/index.js"]
+```
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    build: .
+    environment:
+      - NODE_ENV=production
+    # Logs are structured JSON, perfect for log aggregators
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+```
+
+## 🏆 Best Practices
+
+### 1. Use Semantic Log Levels
+
+```typescript
+// ✅ Good - semantic and meaningful
+logger.log('lifecycle', 'Server starting on port 3000');
+logger.log('success', 'Database connection established');
+logger.log('error', 'Failed to process payment', { orderId, error });
+
+// ❌ Bad - everything is 'info'
+logger.log('info', 'Server starting');
+logger.log('info', 'Database connected');
+logger.log('info', 'Error: payment failed');
+```
+
+### 2. Include Structured Data
+
+```typescript
+// ✅ Good - structured data for analysis
+logger.log('error', 'API request failed', {
+  endpoint: '/api/users',
+  statusCode: 500,
+  duration: 1234,
+  userId: 'usr_123',
+  errorCode: 'INTERNAL_ERROR'
+});
+
+// ❌ Bad - data embedded in message
+logger.log('error', `API request to /api/users failed with 500 in 1234ms for user usr_123`);
+```
+
+### 3. Use Log Groups for Correlation
+
+```typescript
+// ✅ Good - correlated logs
+async function processOrder(orderId: string) {
+  const logGroup = logger.createLogGroup(orderId);
+  
+  logGroup.log('info', 'Processing order');
+  logGroup.log('debug', 'Validating items');
+  logGroup.log('info', 'Charging payment');
+  logGroup.log('success', 'Order processed');
+}
+
+// ❌ Bad - no correlation
+async function processOrder(orderId: string) {
+  logger.log('info', `Processing order ${orderId}`);
+  logger.log('debug', `Validating items for ${orderId}`);
+  logger.log('info', `Charging payment for ${orderId}`);
+}
+```
+
+### 4. Environment-Specific Configuration
+
+```typescript
+// ✅ Good - different configs per environment
+const logger = new Smartlog({
+  logContext: {
+    environment: process.env.NODE_ENV,
+    // ... other context
+  },
+  minimumLogLevel: process.env.NODE_ENV === 'production' ? 'info' : 'silly'
+});
+
+// Add destinations based on environment
+if (process.env.NODE_ENV === 'production') {
+  logger.addLogDestination(clickhouseDestination);
+  logger.addLogDestination(alertingDestination);
+} else {
+  logger.enableConsole();
+}
+```
+
+## 📖 API Reference
+
+### Smartlog Class
+
+```typescript
+class Smartlog {
+  constructor(options?: ISmartlogOptions)
+  
+  // Logging methods
+  log(level: TLogLevel, message: string, data?: any, correlation?: ILogCorrelation): void
+  increment(level: TLogLevel, key: string, data?: any): void
+  
+  // Configuration
+  enableConsole(options?: IConsoleOptions): void
+  addLogDestination(destination: ILogDestination): void
+  addLogContext(context: Partial<ILogContext>): void
+  
+  // Log groups
+  createLogGroup(transactionId?: string): LogGroup
+  createScope(scopeName: string): Smartlog
+}
+```
+
+### Log Levels
+
+```typescript
+type TLogLevel = 
+  | 'silly'      // Very verbose debugging
+  | 'debug'      // Debug information
+  | 'info'       // Informational messages
+  | 'note'       // Notable events
+  | 'ok'         // Success confirmation
+  | 'success'    // Major success
+  | 'warn'       // Warning messages
+  | 'error'      // Error messages
+  | 'lifecycle'  // Application lifecycle events
+```
+
+### Log Package Structure
+
+```typescript
+interface ILogPackage {
+  timestamp: number;
+  level: TLogLevel;
+  message: string;
+  data?: any;
+  context: ILogContext;
+  correlation?: ILogCorrelation;
+}
+```
+
+For complete API documentation, see [API.md](API.md).
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## 📄 License and Legal Information
+
+This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 

test/test.destination-local.node.ts

@@ -92,5 +92,23 @@ tap.test('should create new line(s)', async () => {
   // Multiple lines
   testDestination.newLine(3);
 });
+// Test debug level rendering and fallback for unknown levels
+tap.test('should handle debug and unknown log levels', async () => {
+  testDestination = new DestinationLocal();
+  let out = '';
+  const originalLog = console.log;
+  console.log = (msg: string) => { out += msg; };
+
+  // debug level should render message correctly
+  await testDestination.handleLog(createMockLogPackage('debug', 'debug 🎉'));
+  expect(out).toContain('debug 🎉');
+
+  // fallback for unknown level should still render message
+  out = '';
+  await testDestination.handleLog(createMockLogPackage('verbose' as any, 'verbose ⚠️'));
+  expect(out).toContain('verbose ⚠️');
+
+  console.log = originalLog;
+});
 
 export default tap.start();

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartlog',
-  version: '3.1.2',
+  version: '3.1.9',
   description: 'A minimalistic, distributed, and extensible logging tool supporting centralized log management.'
 }

ts_destination_local/classes.destinationlocal.ts

@@ -61,19 +61,22 @@ export class DestinationLocal implements ILogDestination {
 
   // default logging
   private logToConsole(logPackageArg: ILogPackage) {
-    let logString: string;
     try {
-      logString =
-        this.localBl[logPackageArg.level].prefix +
+      const style = this.localBl[logPackageArg.level] ?? this.localBl.info;
+      const logString =
+        style.prefix +
         plugins.consolecolor.coloredString(
           logPackageArg.message,
-          this.localBl[logPackageArg.level].textColor
+          style.textColor
         );
       console.log(logString);
       return true;
     } catch (error) {
+      // typo fix: use the defined error.prefix, not a non-existent errorPrefix
       console.log(
-        this.localBl.errorPrefix + 'You seem to have tried logging something strange' + error
+        this.localBl.error.prefix +
+          'You seem to have tried logging something strange ' +
+          error
       );
       return false;
     }
@@ -89,6 +92,10 @@ export class DestinationLocal implements ILogDestination {
       prefix: plugins.consolecolor.coloredString(' silly ', 'white', 'blue') + ' ',
       textColor: 'blue',
     },
+    debug: {
+      prefix: plugins.consolecolor.coloredString(' debug ', 'pink', 'black') + ' ',
+      textColor: 'pink',
+    },
     error: {
       prefix:
         plugins.consolecolor.coloredString(' ', 'red', 'red') +