3.1.9

changelog.md

@@ -1,5 +1,44 @@
 # 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
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartlog",
-  "version": "3.1.3",
+  "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.md

@@ -1,288 +1,736 @@
-# @push.rocks/smartlog
+# @push.rocks/smartlog 🚀
+*The ultimate TypeScript logging solution for modern applications*
 
-Minimalistic distributed and extensible logging tool for TypeScript and JavaScript applications.
+[![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. 🎯
 
-Install `@push.rocks/smartlog` using pnpm (recommended), npm, or yarn:
+## 🌟 Why smartlog?
 
-```sh
+- **🎨 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 --save
+npm install @push.rocks/smartlog
 
 # Using yarn
 yarn add @push.rocks/smartlog
 ```
 
-Ensure you have TypeScript and Node.js installed for TypeScript projects.
+## 🚀 Quick Start
 
-## Package Exports
-
-The package provides the following exports:
-
-```javascript
-// Main module
-import { Smartlog, LogGroup, ConsoleLog } from '@push.rocks/smartlog';
-
-// Type definitions and interfaces
-import { ILogPackage, ILogDestination, TLogLevel } from '@push.rocks/smartlog/interfaces';
-
-// Interactive console features (spinners, progress bars)
-import { SmartlogSourceInteractive, SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';
-
-// Context management
-import { ... } from '@push.rocks/smartlog/context';
-
-// Log destinations
-import { SmartlogDestinationClickhouse } from '@push.rocks/smartlog/destination-clickhouse';
-import { SmartlogDestinationDevtools } from '@push.rocks/smartlog/destination-devtools';
-import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';
-import { DestinationLocal } from '@push.rocks/smartlog/destination-local';
-import { SmartlogDestinationReceiver } from '@push.rocks/smartlog/destination-receiver';
-
-// Receiver functionality
-import { SmartlogReceiver } from '@push.rocks/smartlog/receiver';
-```
-
-## Usage
-
-`@push.rocks/smartlog` is a flexible, extensible logging tool designed for distributed systems. It provides a consistent logging interface across different environments while being lightweight and customizable.
-
-### Creating a Logger Instance
-
-Start by importing `Smartlog` and create a logger instance:
+### Your First Logger
 
 ```typescript
 import { Smartlog } from '@push.rocks/smartlog';
 
+// Create a logger with context
 const logger = new Smartlog({
   logContext: {
-    company: 'My Company',
-    companyunit: 'Cloud Team',
-    containerName: 'api-service',
-    environment: 'production', // 'local', 'test', 'staging', 'production'
-    runtime: 'node',           // 'node', 'chrome', 'rust', 'deno', 'cloudflare_workers'
-    zone: 'us-west',
-  },
-  minimumLogLevel: 'info',     // Optional, defaults to 'silly'
+    company: 'MyStartup',
+    companyunit: 'Backend Team',
+    containerName: 'api-gateway',
+    environment: 'production',
+    runtime: 'node',
+    zone: 'eu-central'
+  }
 });
 
-// Enable console output
+// 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 
+});
 ```
 
-The context enriches logs with valuable information for filtering and analysis across distributed systems.
+### Using the Default Logger
 
-### Logging Messages
-
-```typescript
-// Basic logging
-logger.log('info', 'User authenticated successfully');
-logger.log('error', 'Database connection failed', { errorCode: 'DB_CONN_ERR', retryCount: 3 });
-logger.log('warn', 'Rate limit approaching', { currentRate: 95, limit: 100 });
-
-// Log levels: 'silly', 'info', 'debug', 'note', 'ok', 'success', 'warn', 'error', 'lifecycle'
-```
-
-The third parameter accepts any additional data to attach to the log entry.
-
-### Default Logger
-
-For simple cases, use the built-in default logger:
+For quick prototyping and simple applications:
 
 ```typescript
 import { defaultLogger } from '@push.rocks/smartlog';
 
-defaultLogger.log('info', 'Application started');
+defaultLogger.log('info', 'This is so easy!');
 ```
 
-### Log Groups
+## 📚 Core Concepts
 
-Group related logs for better traceability:
+### Log Levels
+
+smartlog supports semantic log levels for different scenarios:
 
 ```typescript
-// Create a log group with optional transaction ID
-const requestGroup = logger.createLogGroup('tx-123456');
+// Lifecycle events
+logger.log('lifecycle', '🔄 Container starting up...');
 
-// Logs within this group will be correlated
-requestGroup.log('info', 'Processing payment request');
-requestGroup.log('debug', 'Validating payment details');
-requestGroup.log('success', 'Payment processed successfully');
+// 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()');
 ```
 
-### Custom Log Destinations
+### Log Groups for Correlation
 
-Extend logging capabilities by adding custom destinations:
+Perfect for tracking request flows through your system:
 
 ```typescript
-import { Smartlog, ILogDestination } from '@push.rocks/smartlog';
+// Track a user request through multiple operations
+const requestGroup = logger.createLogGroup('req-7f3a2b');
 
-class DatabaseLogDestination implements ILogDestination {
-  async handleLog(logPackage) {
-    // Store log in database
-    await db.logs.insert({
-      timestamp: new Date(logPackage.timestamp),
-      level: logPackage.level,
-      message: logPackage.message,
-      data: logPackage.data,
-      context: logPackage.context
+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
+      }
     });
   }
 }
 
-// Add the custom destination to your logger
-logger.addLogDestination(new DatabaseLogDestination());
-```
-
-### Built-in Destinations
-
-SmartLog comes with several built-in destinations for various logging needs:
-
-```typescript
-// Log to a file
-import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';
-logger.addLogDestination(new SmartlogDestinationFile('/path/to/logfile.log'));
-
-// Colorful local console logging
-import { DestinationLocal } from '@push.rocks/smartlog/destination-local';
-logger.addLogDestination(new DestinationLocal());
-
-// Browser DevTools with colored formatting
-import { SmartlogDestinationDevtools } from '@push.rocks/smartlog/destination-devtools';
-logger.addLogDestination(new SmartlogDestinationDevtools());
-
-// ClickHouse database logging
-import { SmartlogDestinationClickhouse } from '@push.rocks/smartlog/destination-clickhouse';
-const clickhouse = await SmartlogDestinationClickhouse.createAndStart({
-  host: 'clickhouse.example.com',
-  port: 8123,
-  user: 'username',
-  password: 'password',
-  database: 'logs_db'
-});
-logger.addLogDestination(clickhouse);
-
-// Remote receiver logging
-import { SmartlogDestinationReceiver } from '@push.rocks/smartlog/destination-receiver';
-logger.addLogDestination(new SmartlogDestinationReceiver({
-  endpoint: 'https://logs.example.com/api/logs'
+// Use your custom destination
+logger.addLogDestination(new ElasticsearchDestination({
+  node: 'https://elasticsearch.example.com'
 }));
 ```
 
-### Interactive Console Features
+## 🎨 Interactive Console Features
 
-For CLI applications, use the interactive console features:
+### Spinners
+
+Create beautiful loading animations that degrade gracefully in CI/CD:
 
 ```typescript
-import { SmartlogSourceInteractive, SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';
-```
+import { SmartlogSourceInteractive } from '@push.rocks/smartlog/source-interactive';
 
-#### Spinners
-
-```typescript
 const spinner = new SmartlogSourceInteractive();
 
-// Start a spinner with text
-spinner.text('Loading data...');
+// Basic usage
+spinner.text('🔄 Fetching data from API...');
+// ... perform async operation
+spinner.finishSuccess('✅ Data fetched successfully!');
+
+// Chained operations
+spinner
+  .text('📡 Connecting to database')
+  .successAndNext('🔍 Running migrations')
+  .successAndNext('🌱 Seeding data')
+  .finishSuccess('🎉 Database ready!');
 
 // Customize appearance
-spinner.setSpinnerStyle('dots');  // 'dots', 'line', 'star', 'simple'
-spinner.setColor('blue');         // 'red', 'green', 'yellow', 'blue', etc.
-spinner.setSpeed(80);             // Animation speed in milliseconds
+spinner
+  .setSpinnerStyle('dots')  // dots, line, star, simple
+  .setColor('cyan')         // any terminal color
+  .setSpeed(80)            // animation speed in ms
+  .text('🚀 Deploying application...');
 
-// Update spinner status
-spinner.text('Processing records...');
-
-// Complete with success or failure
-spinner.finishSuccess('Data loaded successfully!');
-spinner.finishFail('Failed to load data!');
-
-// Chain operations
-spinner.text('Connecting to server')
-  .successAndNext('Fetching records')
-  .successAndNext('Processing data')
-  .finishSuccess('All done!');
+// Handle failures
+try {
+  await deployApp();
+  spinner.finishSuccess('✅ Deployed!');
+} catch (error) {
+  spinner.finishFail('❌ Deployment failed');
+}
 ```
 
-#### Progress Bars
+### Progress Bars
+
+Track long-running operations with style:
 
 ```typescript
-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")
+import { SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';
+
+// Create a progress bar
+const progress = new SmartlogProgressBar({
+  total: 100,
+  width: 40,
+  complete: '█',
+  incomplete: '░',
+  showEta: true,
+  showPercent: true,
+  showCount: true
 });
 
 // Update progress
-progressBar.update(25);      // Set to 25% progress
+for (let i = 0; i <= 100; i++) {
+  progress.update(i);
+  await someAsyncWork();
+}
 
-// Increment progress
-progressBar.increment(5);    // Increase by 5 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.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) and fallback to plain text logging:
+Both spinners and progress bars automatically detect non-interactive environments (CI/CD, Docker logs, piped output) and fallback to simple text output:
 
 ```
-[Loading] Connecting to server
-[Success] Connected to server
-[Loading] Fetching records
+[Loading] Connecting to database
+[Success] Connected to database
+[Loading] Running migrations
+Progress: 25% (25/100)
 Progress: 50% (50/100)
 Progress: 100% (100/100)
-[Success] Fetching complete
+[Success] Migrations complete
 ```
 
-## Advanced Usage
+## 🔧 Advanced Features
 
-### Capturing All Console Output
+### Context Management
 
-Capture all `console.log` and `console.error` output through Smartlog:
+Add context that flows through your entire application:
 
 ```typescript
-logger.enableConsole({ captureAll: true });
+// Set global context
+logger.addLogContext({
+  requestId: 'req-123',
+  userId: 'user-456',
+  feature: 'payment-processing'
+});
+
+// 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
 
-For metrics and counters:
+Perfect for metrics and counters:
 
 ```typescript
-logger.increment('info', 'api_requests', { endpoint: '/users' });
+// 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' });
 ```
 
-### Log Correlation
+### Capture All Console Output
 
-Correlate logs across services with correlation IDs:
+Redirect all console.log and console.error through smartlog:
 
 ```typescript
-logger.log('info', 'Request received', { userId: 'user-123' }, {
-  id: 'req-abc-123',
-  type: 'service',
-  transaction: 'tx-payment-456'
+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();
 });
 ```
 
-## API Documentation
+### CLI Tool with Progress Tracking
 
-For detailed API documentation, see the [API.md](API.md) file.
+```typescript
+import { Smartlog } from '@push.rocks/smartlog';
+import { SmartlogSourceInteractive, SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';
 
-## License and Legal Information
+const logger = new Smartlog({
+  logContext: {
+    containerName: 'migration-tool',
+    environment: 'cli'
+  }
+});
 
-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.
+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!');
+}
+```
+
+### Production Logging with Multiple Destinations
+
+```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';
+
+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
+});
+
+// Console for container logs (structured for log aggregators)
+logger.addLogDestination(new DestinationLocal());
+
+// File for audit trail
+logger.addLogDestination(new SmartlogDestinationFile('/var/log/app/audit.log'));
+
+// Central logging service
+logger.addLogDestination(new SmartlogDestinationReceiver({
+  endpoint: 'https://logs.enterprise.com/ingest',
+  apiKey: process.env.LOG_API_KEY,
+  batchSize: 100,
+  flushInterval: 5000
+}));
+
+// 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
+      });
+    }
+  }
+});
+```
+
+## 🔌 Integration with Other Tools
+
+### PM2 Integration
+
+```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
+    }
+  }]
+};
+```
+
+### 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.3',
+  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') +