@mks2508/better-logger 5.0.0 → 5.0.2

package/docs/API.md

@@ -1,918 +0,0 @@
----
-layout: default
-title: API Reference
-permalink: /API/
----
-
-# 🔧 API Reference
-
-Complete API documentation for Better Logger with detailed method signatures, parameters, and examples.
-
-## Table of Contents
-
-- [Core Logger](#core-logger)
-- [Enterprise Features (v3.0.0)](#enterprise-features-v300)
-  - [Custom Serializers](#custom-serializers)
-  - [Hooks & Middleware](#hooks--middleware)
-  - [Transports](#transports)
-- [Style Builder](#style-builder)
-- [CLI Interface](#cli-interface)
-- [Export & Remote](#export--remote)
-- [Types & Interfaces](#types--interfaces)
-
----
-
-## 🚀 Core Logger
-
-### Logger Class
-
-The main Logger class provides all essential logging functionality.
-
-```typescript
-import { Logger } from '@mks2508/better-logger';
-
-const logger = new Logger();
-```
-
-#### Constructor Options
-
-```typescript
-interface LoggerOptions {
-  prefix?: string;           // Default prefix for all log messages
-  level?: LogLevel;          // Minimum log level to display
-  enableStackTrace?: boolean; // Include stack traces in logs
-  enablePerformance?: boolean; // Include performance timings
-  theme?: ThemeName;         // Visual theme for styling
-}
-```
-
-#### Log Levels
-
-```typescript
-type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'critical';
-
-// Log level hierarchy (higher numbers = higher priority)
-const LOG_LEVELS = {
-  debug: 0,
-  info: 1,
-  warn: 2,
-  error: 3,
-  critical: 4
-} as const;
-```
-
-### Basic Logging Methods
-
-#### `logger.debug(message, ...args)`
-Low-priority debugging information.
-```typescript
-logger.debug('Variable value:', { userId: 123 });
-// Output: [DEBUG] Variable value: { userId: 123 }
-```
-
-#### `logger.info(message, ...args)`
-General informational messages.
-```typescript
-logger.info('User logged in', { username: 'john_doe' });
-// Output: [INFO] User logged in { username: 'john_doe' }
-```
-
-#### `logger.warn(message, ...args)`
-Warning messages for potential issues.
-```typescript
-logger.warn('API rate limit approaching', { remaining: 10 });
-// Output: [WARN] API rate limit approaching { remaining: 10 }
-```
-
-#### `logger.error(message, ...args)`
-Error messages for failures.
-```typescript
-logger.error('Database connection failed', { error: 'ECONNREFUSED' });
-// Output: [ERROR] Database connection failed { error: 'ECONNREFUSED' }
-```
-
-#### `logger.critical(message, ...args)`
-Critical system failures requiring immediate attention.
-```typescript
-logger.critical('System memory exhausted', { usage: '95%' });
-// Output: [CRITICAL] System memory exhausted { usage: '95%' }
-```
-
-### Advanced Logging Methods
-
-#### `logger.success(message, ...args)`
-Success notifications with green styling.
-```typescript
-logger.success('Payment processed successfully', { orderId: 'ORD-123' });
-// Output: [SUCCESS] Payment processed successfully { orderId: 'ORD-123' }
-```
-
-#### `logger.table(data, options?)`
-Display data in formatted table.
-```typescript
-const users = [
-  { id: 1, name: 'John', email: 'john@example.com' },
-  { id: 2, name: 'Jane', email: 'jane@example.com' }
-];
-
-logger.table(users);
-// Displays formatted table in console
-```
-
-#### `logger.group(label, callback?)`
-Group related log messages.
-```typescript
-logger.group('User Authentication', () => {
-  logger.info('Checking credentials...');
-  logger.info('Validating token...');
-  logger.success('Authentication successful');
-});
-
-// Or manual grouping
-logger.group('Database Operations');
-logger.info('Connecting to database...');
-logger.info('Running migration...');
-logger.groupEnd();
-```
-
-### Performance Timing
-
-#### `logger.time(label)`
-Start timing operation.
-```typescript
-logger.time('api-call');
-await fetchUserData();
-logger.timeEnd('api-call');
-// Output: [TIMING] api-call: 245.67ms
-```
-
-#### `logger.timeEnd(label)`
-End timing and display duration.
-
-#### `logger.timeLog(label, ...args)`
-Log intermediate timing without ending timer.
-```typescript
-logger.time('long-operation');
-await step1();
-logger.timeLog('long-operation', 'Step 1 complete');
-await step2();
-logger.timeEnd('long-operation');
-```
-
-### Scoped Loggers
-
-Create loggers with persistent prefixes for different modules.
-
-```typescript
-const apiLogger = logger.scope('API');
-const dbLogger = logger.scope('DATABASE');
-
-apiLogger.info('Making HTTP request');    // [API] [INFO] Making HTTP request
-dbLogger.error('Connection timeout');     // [DATABASE] [ERROR] Connection timeout
-```
-
-### Log Handlers
-
-Add custom handlers for log processing.
-
-```typescript
-import { FileLogHandler, RemoteLogHandler } from '@mks2508/better-logger';
-
-// File logging
-logger.addHandler(new FileLogHandler('/path/to/logs.txt'));
-
-// Remote logging
-logger.addHandler(new RemoteLogHandler('https://api.logging-service.com'));
-
-// Custom handler
-logger.addHandler({
-  handle(entry) {
-    // Process log entry
-    console.log('Custom handler:', entry);
-  }
-});
-```
-
----
-
-## 🔄 Enterprise Features (v3.0.0)
-
-### Custom Serializers
-
-Transform objects before logging with type-based serializers.
-
-#### `logger.addSerializer(type, serializer, priority?)`
-Register a serializer for a specific type.
-
-```typescript
-// Serialize Error objects
-logger.addSerializer(Error, (err) => ({
-  name: err.name,
-  message: err.message,
-  stack: err.stack?.split('\n').slice(0, 5)
-}));
-
-// Serialize User objects (omit sensitive data)
-logger.addSerializer(User, (user) => ({
-  id: user.id,
-  email: user.email
-  // password automatically omitted
-}), 100);  // higher priority
-
-// Now objects are serialized automatically
-logger.error('Failed:', new Error('Connection timeout'));
-logger.info('User:', currentUser);
-```
-
-#### `logger.removeSerializer(type)`
-Remove a registered serializer.
-
-```typescript
-logger.removeSerializer(Error);
-```
-
-#### `logger.getSerializerRegistry()`
-Access the SerializerRegistry for advanced operations.
-
-```typescript
-const registry = logger.getSerializerRegistry();
-const serialized = registry.serialize(complexObject);
-```
-
-### Hooks & Middleware
-
-Intercept and modify log entries with hooks and middleware.
-
-#### `logger.on(event, callback, priority?)`
-Register a hook for an event. Returns unsubscribe function.
-
-```typescript
-// Add correlation ID to all logs
-const unsubscribe = logger.on('beforeLog', (entry) => {
-  entry.correlationId = getCorrelationId();
-  return entry;  // Return modified entry
-});
-
-// Track metrics after logging
-logger.on('afterLog', (entry) => {
-  metrics.increment(`logs.${entry.level}`);
-});
-
-// Handle errors
-logger.on('onError', (entry) => {
-  alertSystem.notify(entry.message);
-});
-
-// Unsubscribe when done
-unsubscribe();
-```
-
-#### `logger.once(event, callback, priority?)`
-Register a hook that fires only once.
-
-```typescript
-logger.once('beforeLog', (entry) => {
-  console.log('First log entry:', entry.message);
-});
-```
-
-#### `logger.off(event, callback)`
-Remove a registered hook.
-
-```typescript
-const myHook = (entry) => { /* ... */ };
-logger.on('beforeLog', myHook);
-// Later...
-logger.off('beforeLog', myHook);
-```
-
-#### `logger.use(middleware, priority?)`
-Add middleware to the processing pipeline.
-
-```typescript
-// Add request context
-logger.use((entry, next) => {
-  entry.requestId = asyncLocalStorage.getStore()?.requestId;
-  next();  // Continue to next middleware
-});
-
-// Redact sensitive data
-logger.use((entry, next) => {
-  entry.message = entry.message.replace(/password=\S+/g, 'password=***');
-  next();
-});
-
-// Middleware with priority (higher = runs first)
-logger.use((entry, next) => {
-  entry.timestamp = new Date().toISOString();
-  next();
-}, 100);
-```
-
-#### Hook Events
-
-| Event | Description | Can Modify Entry |
-|-------|-------------|------------------|
-| `beforeLog` | Before log is processed | Yes |
-| `afterLog` | After log is output | No |
-| `onError` | When an error occurs | No |
-
-### Transports
-
-Send logs to multiple destinations with the transport system.
-
-#### `logger.addTransport(target)`
-Add a transport destination. Returns transport ID.
-
-```typescript
-// Built-in file transport (Node.js)
-const fileId = logger.addTransport({
-  target: 'file',
-  options: { destination: '/var/log/app.log' }
-});
-
-// Built-in HTTP transport with batching
-const httpId = logger.addTransport({
-  target: 'http',
-  options: {
-    url: 'https://logs.example.com/ingest',
-    headers: { 'Authorization': 'Bearer token' },
-    batchSize: 100,      // Send in batches of 100
-    flushInterval: 5000  // Or every 5 seconds
-  },
-  level: 'warn'  // Only warn and above
-});
-
-// Built-in console transport
-logger.addTransport({
-  target: 'console'
-});
-
-// Custom transport
-logger.addTransport({
-  target: {
-    name: 'elasticsearch',
-    write: async (record) => {
-      await esClient.index({
-        index: 'logs',
-        body: record
-      });
-    },
-    flush: async () => {
-      await esClient.indices.refresh({ index: 'logs' });
-    },
-    close: async () => {
-      await esClient.close();
-    }
-  }
-});
-```
-
-#### `logger.removeTransport(id)`
-Remove a transport by ID.
-
-```typescript
-logger.removeTransport(fileId);
-```
-
-#### `logger.flushTransports()`
-Force flush all transport buffers.
-
-```typescript
-await logger.flushTransports();
-```
-
-#### `logger.closeTransports()`
-Close all transports (flush + cleanup).
-
-```typescript
-// Before application shutdown
-await logger.closeTransports();
-```
-
-#### Transport Record Structure
-
-```typescript
-interface TransportRecord {
-  level: LogLevel;
-  levelValue: number;  // 0-4
-  time: number;        // Unix timestamp
-  msg: string;
-  prefix?: string;
-  location?: {
-    file: string;
-    line: number;
-    column: number;
-    function?: string;
-  };
-}
-```
-
-#### Built-in Transports
-
-| Transport | Description | Options |
-|-----------|-------------|---------|
-| `console` | Console output | - |
-| `file` | File logging (Node.js) | `destination`, `batchSize`, `flushInterval` |
-| `http` | HTTP/HTTPS endpoint | `url`, `headers`, `batchSize`, `flushInterval` |
-
----
-
-## 🎨 Style Builder
-
-Create custom console styles programmatically.
-
-```typescript
-import { createStyle, StyleBuilder } from '@mks2508/better-logger/styling';
-```
-
-### Creating Styles
-
-#### `createStyle()`
-Returns new StyleBuilder instance.
-
-```typescript
-const customStyle = createStyle()
-  .bg('linear-gradient(45deg, #ff6b6b, #feca57)')
-  .color('white')
-  .padding('10px 20px')
-  .rounded('8px')
-  .bold()
-  .build();
-
-console.log('%cCustom Message', customStyle);
-```
-
-### StyleBuilder Methods
-
-#### Background Methods
-```typescript
-.bg(gradient: string)                    // Background gradient
-.backgroundColor(color: string)          // Solid background color
-```
-
-#### Typography Methods
-```typescript
-.color(color: string)                    // Text color
-.font(family: string)                    // Font family
-.fontSize(size: string)                  // Font size
-.bold()                                  // Bold text
-.italic()                                // Italic text
-```
-
-#### Layout Methods
-```typescript
-.padding(padding: string)                // CSS padding
-.margin(margin: string)                  // CSS margin
-.display(display: string)                // CSS display property
-```
-
-#### Visual Effects
-```typescript
-.border(border: string)                  // CSS border
-.rounded(radius: string)                 // Border radius
-.shadow(shadow: string)                  // Box shadow
-```
-
-#### Animations
-```typescript
-.animation(animation: string)            // CSS animation
-.transition(transition: string)          // CSS transition
-```
-
-#### Custom Properties
-```typescript
-.css(property: string, value: string)    // Custom CSS property
-```
-
-### Style Presets
-
-Pre-built styles for common use cases.
-
-```typescript
-import { stylePresets } from '@mks2508/better-logger/styling';
-
-console.log('%c✅ Success!', stylePresets.success);
-console.log('%c❌ Error!', stylePresets.error);
-console.log('%c⚠️ Warning!', stylePresets.warning);
-console.log('%cℹ️ Info', stylePresets.info);
-console.log('%c🎯 Accent', stylePresets.accent);
-```
-
----
-
-## 💻 CLI Interface
-
-Enhanced interactive command-line interface with plugin support, command history, and intelligent suggestions.
-
-### 🔌 Plugin System
-
-Extend CLI functionality with custom plugins:
-
-```typescript
-import { logger } from '@mks2508/better-logger';
-
-// Create a custom plugin
-const analyticsPlugin = {
-    name: 'analytics',
-    version: '1.0.0', 
-    description: 'Analytics tracking commands',
-    commands: [{
-        name: 'track',
-        description: 'Track user events',
-        usage: '/track <event> <data>',
-        category: 'analytics',
-        aliases: ['t'],
-        execute: (args, logger) => {
-            const [event, ...data] = args.split(' ');
-            logger.info(`📊 Tracking: ${event}`, data.join(' '));
-        }
-    }]
-};
-
-// Register the plugin
-logger.cliProcessor.registerPlugin(analyticsPlugin, logger);
-```
-
-### 🌐 Interactive Mode
-
-Enter interactive mode for streamlined browser console usage:
-
-```typescript
-// Enter interactive mode
-logger.executeCommand('/interactive');
-
-// Now use commands directly:
-cli('help');           // Instead of logger.executeCommand('/help')  
-cli('theme matrix');   // Change theme interactively
-cli('history 5');      // Show last 5 commands
-```
-
-### 📋 Enhanced Commands
-
-#### Core Commands
-
-##### `/help`
-Display help information and available commands.
-```typescript
-logger.executeCommand('/help');
-```
-
-##### `/config`  
-Show current logger configuration.
-```typescript
-logger.executeCommand('/config');
-// Displays: Theme: default, Level: info, Stack traces: enabled
-```
-
-##### `/history [limit]` | Aliases: `/hist`, `/h`
-View command execution history with success/failure status.
-```typescript
-logger.executeCommand('/history 10');     // Show last 10 commands
-logger.executeCommand('/hist');           // Show default (10) recent commands
-// ✅ [14:32:15] /theme matrix
-// ❌ [14:31:45] /invalid-command  
-// ✅ [14:30:22] /export csv
-```
-
-##### `/clearhistory` | Aliases: `/clrhist`
-Clear all command history.
-```typescript
-logger.executeCommand('/clearhistory');
-// 🗑️ Command history cleared
-```
-
-##### `/interactive` | Aliases: `/i`, `/repl`
-Enter interactive CLI mode for browser console.
-```typescript
-logger.executeCommand('/interactive');
-// 🔧 Interactive CLI mode activated. Type /exit to quit, /help for commands.
-// 💡 Use cli("command") to execute CLI commands in browser console.
-```
-
-##### `/plugins` | Aliases: `/plug`
-List all registered plugins and their commands.
-```typescript
-logger.executeCommand('/plugins');
-// 🔌 Loaded plugins (2):
-//   📦 analytics v1.0.0 - Analytics tracking commands
-//      Commands: track, event
-//   📦 performance v2.1.0 - Performance monitoring tools  
-//      Commands: benchmark, profile
-```
-
-#### `/theme [name]`
-Change visual theme.
-```typescript
-/theme cyberpunk
-// Switches to cyberpunk theme with purple/pink colors
-```
-
-Available themes: `default`, `dark`, `neon`, `cyberpunk`, `retro`
-
-#### `/banner [type]`
-Set banner display type.
-```typescript
-/banner animated
-// Shows animated gradient banner
-```
-
-Banner types: `simple`, `ascii`, `unicode`, `svg`, `animated`
-
-#### `/clear`
-Clear console and reset log buffer.
-
-#### `/export [format]`
-Export logs in specified format.
-```typescript
-/export json
-// Exports current logs as JSON
-```
-
-#### `/status`
-Show logger status and statistics.
-
-#### `/enumerate`
-List all available features and capabilities.
-
-### CLI Integration
-
-```typescript
-import { initializeCLI } from '@mks2508/better-logger/cli';
-
-// Initialize CLI with logger instance
-initializeCLI(logger);
-
-// CLI commands are now available in console
-// Type /help to see available commands
-```
-
----
-
-## 📤 Export & Remote
-
-Data export and remote logging capabilities.
-
-```typescript
-import { ExportLogger } from '@mks2508/better-logger/exports';
-```
-
-### ExportLogger Class
-
-Extended logger with export and remote capabilities.
-
-```typescript
-const logger = new ExportLogger({
-  bufferSize: 1000,
-  remoteBatch: {
-    size: 10,
-    interval: 5000
-  }
-});
-```
-
-#### Constructor Options
-```typescript
-interface ExportLoggerConfig {
-  bufferSize?: number;           // Log buffer size
-  bufferMode?: 'circular' | 'grow'; // Buffer behavior
-  persistBuffer?: boolean;       // Save to localStorage
-  remoteBatch?: {               // Remote batching config
-    size: number;
-    interval: number;
-    maxWait: number;
-  };
-  autoExport?: {               // Auto-export settings
-    format: ExportFormat;
-    trigger: 'size' | 'time' | 'level';
-    threshold: number;
-  };
-}
-```
-
-### Export Methods
-
-#### `exportLogs(format, options?)`
-Export logs in specified format.
-
-```typescript
-// Export as CSV
-const csvData = await logger.exportLogs('csv', {
-  filter: { level: 'error' },
-  limit: 100
-});
-
-// Export as JSON with grouping
-const jsonData = await logger.exportLogs('json', {
-  groupBy: 'level',
-  includeStackTrace: true
-});
-
-// Export as XML
-const xmlData = await logger.exportLogs('xml');
-```
-
-#### Export Options
-```typescript
-interface ExportOptions {
-  filter?: {
-    level?: LogLevel | LogLevel[];
-    from?: Date | string;
-    to?: Date | string;
-    prefix?: string | string[];
-    content?: string;
-  };
-  limit?: number;
-  groupBy?: 'level' | 'prefix' | 'date';
-  includeStackTrace?: boolean;
-  minimal?: boolean;
-}
-```
-
-### Remote Logging
-
-#### `addRemoteHandler(url, options?)`
-Add remote logging endpoint.
-
-```typescript
-// HTTP endpoint
-logger.addRemoteHandler('https://api.logs.com/collect', {
-  apiKey: 'secret-key',
-  headers: { 'Content-Type': 'application/json' },
-  retries: 3
-});
-
-// WebSocket endpoint
-logger.addRemoteHandler('wss://realtime.logs.com', {
-  reconnect: true,
-  maxReconnectAttempts: 5
-});
-```
-
-#### Remote Handler Options
-```typescript
-interface RemoteHandlerOptions {
-  apiKey?: string;
-  headers?: Record<string, string>;
-  retries?: number;
-  timeout?: number;
-  reconnect?: boolean;
-  reconnectInterval?: number;
-  maxReconnectAttempts?: number;
-  filter?: (entry: LogEntry) => boolean;
-  immediate?: boolean;
-}
-```
-
----
-
-## 📋 Types & Interfaces
-
-### Core Types
-
-```typescript
-// Log levels
-type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'critical';
-
-// Theme names
-type ThemeName = 'default' | 'dark' | 'neon' | 'cyberpunk' | 'retro';
-
-// Banner types
-type BannerType = 'simple' | 'ascii' | 'unicode' | 'svg' | 'animated';
-
-// Export formats
-type ExportFormat = 'csv' | 'json' | 'xml';
-```
-
-### Interfaces
-
-```typescript
-// Log entry structure
-interface LogEntry {
-  id: string;
-  timestamp: string;
-  level: LogLevel;
-  prefix: string;
-  message: string;
-  args: any[];
-  location?: {
-    file: string;
-    line: number;
-    column: number;
-    function: string;
-  };
-  performance?: {
-    duration: number;
-    memory: NodeJS.MemoryUsage;
-  };
-}
-
-// Log handler interface
-interface ILogHandler {
-  handle(entry: LogEntry): void | Promise<void>;
-}
-
-// Style configuration
-interface StyleConfig {
-  emoji?: string;
-  colors?: {
-    primary: string;
-    secondary: string;
-    text: string;
-  };
-  effects?: {
-    shadow: string;
-    border: string;
-  };
-}
-```
-
----
-
-## 🔄 Lifecycle Events
-
-### Event Handlers
-
-```typescript
-// Log events
-logger.on('log', (entry: LogEntry) => {
-  // Handle each log entry
-});
-
-logger.on('error', (error: Error) => {
-  // Handle logging errors
-});
-
-logger.on('export', (data: string, format: ExportFormat) => {
-  // Handle export completion
-});
-
-// Remote events
-logger.on('remote:success', (endpoint: string, count: number) => {
-  // Handle successful remote transmission
-});
-
-logger.on('remote:error', (endpoint: string, error: Error) => {
-  // Handle remote logging errors
-});
-```
-
-### Buffer Events
-
-```typescript
-logger.on('buffer:full', (size: number) => {
-  // Handle buffer capacity reached
-});
-
-logger.on('buffer:cleared', () => {
-  // Handle buffer cleared
-});
-```
-
----
-
-## 📚 Advanced Usage
-
-### Performance Monitoring
-
-```typescript
-// Automatic performance tracking
-logger.time('operation');
-await performOperation();
-const metrics = logger.timeEnd('operation'); // Returns timing data
-
-// Memory usage tracking
-logger.logMemory('checkpoint-1');
-await heavyOperation();
-logger.logMemory('checkpoint-2');
-```
-
-### Conditional Logging
-
-```typescript
-// Environment-based logging
-logger.setLevel(process.env.NODE_ENV === 'production' ? 'warn' : 'debug');
-
-// Conditional handlers
-if (process.env.ENABLE_FILE_LOGGING === 'true') {
-  logger.addHandler(new FileLogHandler('./app.log'));
-}
-```
-
-### Custom Formatters
-
-```typescript
-// Custom message formatting
-logger.setFormatter((entry: LogEntry) => {
-  return `[${entry.timestamp}] ${entry.level.toUpperCase()}: ${entry.message}`;
-});
-
-// Custom data serialization
-logger.setSerializer((data: any) => {
-  return JSON.stringify(data, null, 2);
-});
-```
-
----
-
-For more examples and use cases, see the [examples folder](../examples/) and [live demo](https://mks2508.github.io/advanced-logger/).