@mks2508/better-logger 3.0.0 → 4.0.0

package/src/terminal/formatter.ts

@@ -0,0 +1,236 @@
+/**
+ * Terminal Formatter - Alignment, key-value, and advanced terminal formatting
+ */
+
+import { getTerminalWidth } from '../utils/environment-detector.js';
+import { getANSIForeground, ANSI, type ColorCapability } from './color-converter.js';
+import type { ColumnConfig, ColumnAlign, BadgeStyle, TimestampFormat, LogOptions } from '../types/index.js';
+
+export function stripAnsi(str: string): string {
+    return str.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+export function getVisibleLength(str: string): number {
+    return stripAnsi(str).length;
+}
+
+export function padToWidth(str: string, width: number, align: ColumnAlign = 'left'): string {
+    const visibleLen = getVisibleLength(str);
+    if (visibleLen >= width) return str;
+
+    const padding = width - visibleLen;
+
+    switch (align) {
+        case 'right':
+            return ' '.repeat(padding) + str;
+        case 'center':
+            const leftPad = Math.floor(padding / 2);
+            const rightPad = padding - leftPad;
+            return ' '.repeat(leftPad) + str + ' '.repeat(rightPad);
+        case 'left':
+        default:
+            return str + ' '.repeat(padding);
+    }
+}
+
+export function formatWithRightAlign(
+    leftContent: string,
+    rightContent: string,
+    maxWidth?: number
+): string {
+    const width = maxWidth ?? getTerminalWidth();
+    const leftLen = getVisibleLength(leftContent);
+    const rightLen = getVisibleLength(rightContent);
+
+    const gap = width - leftLen - rightLen;
+    if (gap <= 1) {
+        return `${leftContent} ${rightContent}`;
+    }
+
+    return `${leftContent}${' '.repeat(gap)}${rightContent}`;
+}
+
+export function formatColumns(
+    columns: ColumnConfig[],
+    maxWidth?: number,
+    colorCapability: ColorCapability = 'full'
+): string {
+    const width = maxWidth ?? getTerminalWidth();
+    const totalColumns = columns.length;
+
+    const columnsWithWidths = columns.map((col, idx) => {
+        if (col.width) return { ...col, calculatedWidth: col.width };
+
+        const remainingWidth = width - columns
+            .filter((c, i) => i !== idx && c.width)
+            .reduce((sum, c) => sum + (c.width ?? 0), 0);
+
+        const autoColumns = columns.filter(c => !c.width).length;
+        const calculatedWidth = Math.floor(remainingWidth / autoColumns);
+
+        return { ...col, calculatedWidth };
+    });
+
+    return columnsWithWidths.map(col => {
+        let content = col.content;
+
+        if (col.color && colorCapability !== 'none') {
+            const colorCode = getANSIForeground(col.color, colorCapability);
+            content = `${colorCode}${content}${ANSI.reset}`;
+        }
+
+        return padToWidth(content, col.calculatedWidth, col.align);
+    }).join('');
+}
+
+export function formatKeyValue(
+    obj: Record<string, unknown>,
+    colorCapability: ColorCapability = 'full',
+    options: { separator?: string; keyColor?: string; valueColor?: string } = {}
+): string {
+    const {
+        separator = '  ',
+        keyColor = '#888888',
+        valueColor = '#00ffff'
+    } = options;
+
+    const entries = Object.entries(obj);
+    if (entries.length === 0) return '';
+
+    const keyColorCode = colorCapability !== 'none'
+        ? getANSIForeground(keyColor, colorCapability)
+        : '';
+    const valueColorCode = colorCapability !== 'none'
+        ? getANSIForeground(valueColor, colorCapability)
+        : '';
+    const reset = colorCapability !== 'none' ? ANSI.reset : '';
+
+    return entries
+        .map(([key, value]) => {
+            const valueStr = typeof value === 'object'
+                ? JSON.stringify(value)
+                : String(value);
+            return `${keyColorCode}${key}:${reset} ${valueColorCode}${valueStr}${reset}`;
+        })
+        .join(separator);
+}
+
+export function isKeyValueObject(obj: unknown): obj is Record<string, unknown> {
+    if (typeof obj !== 'object' || obj === null) return false;
+    if (Array.isArray(obj)) return false;
+
+    const proto = Object.getPrototypeOf(obj);
+    if (proto !== Object.prototype && proto !== null) return false;
+
+    const values = Object.values(obj);
+    return values.every(v =>
+        typeof v === 'string' ||
+        typeof v === 'number' ||
+        typeof v === 'boolean' ||
+        v === null
+    );
+}
+
+export function formatBadge(
+    badge: string,
+    style: BadgeStyle = 'brackets',
+    colorCapability: ColorCapability = 'full',
+    color?: string
+): string {
+    const colorCode = color && colorCapability !== 'none'
+        ? getANSIForeground(color, colorCapability)
+        : '';
+    const reset = colorCapability !== 'none' ? ANSI.reset : '';
+    const bgBlack = colorCapability !== 'none' ? ANSI.bg.black : '';
+
+    const text = badge.toUpperCase();
+
+    switch (style) {
+        case 'rounded':
+            return `${bgBlack}${colorCode}⟨${text}⟩${reset}`;
+        case 'plain':
+            return `${colorCode}${text}${reset}`;
+        case 'unicode':
+            return `${bgBlack}${colorCode}╭${text}╮${reset}`;
+        case 'pill':
+            return `${bgBlack}${colorCode}⦗${text}⦘${reset}`;
+        case 'brackets':
+        default:
+            return `${bgBlack}${colorCode}[${text}]${reset}`;
+    }
+}
+
+export function formatTimestamp(
+    date: Date = new Date(),
+    format: TimestampFormat = 'time'
+): string {
+    switch (format) {
+        case 'iso':
+            return date.toISOString();
+        case 'date':
+            return date.toISOString().split('T')[0] ?? '';
+        case 'time':
+            return date.toTimeString().slice(0, 8);
+        case 'timeMs':
+            return date.toTimeString().slice(0, 8) + '.' +
+                   String(date.getMilliseconds()).padStart(3, '0');
+        case 'relative':
+            return formatRelativeTime(date);
+        case 'elapsed':
+            return formatElapsedTime(date);
+        case 'custom':
+        default:
+            return date.toLocaleTimeString();
+    }
+}
+
+let startTime: number | null = null;
+
+export function formatRelativeTime(date: Date): string {
+    if (startTime === null) {
+        startTime = Date.now();
+    }
+
+    const diff = date.getTime() - startTime;
+
+    if (diff < 1000) {
+        return `+${diff}ms`;
+    } else if (diff < 60000) {
+        return `+${(diff / 1000).toFixed(1)}s`;
+    } else {
+        const mins = Math.floor(diff / 60000);
+        const secs = Math.floor((diff % 60000) / 1000);
+        return `+${mins}m${secs}s`;
+    }
+}
+
+export function formatElapsedTime(date: Date): string {
+    if (startTime === null) {
+        startTime = Date.now();
+    }
+
+    const diff = date.getTime() - startTime;
+    const hours = Math.floor(diff / 3600000);
+    const mins = Math.floor((diff % 3600000) / 60000);
+    const secs = Math.floor((diff % 60000) / 1000);
+
+    return `${String(hours).padStart(2, '0')}:${String(mins).padStart(2, '0')}:${String(secs).padStart(2, '0')}`;
+}
+
+export function resetStartTime(): void {
+    startTime = Date.now();
+}
+
+export function applyLogOptions(
+    message: string,
+    options: LogOptions,
+    colorCapability: ColorCapability = 'full'
+): string {
+    let result = message;
+
+    if (options.rightAlign) {
+        result = formatWithRightAlign(message, options.rightAlign);
+    }
+
+    return result;
+}

package/src/terminal/terminal-renderer.ts

@@ -5,6 +5,7 @@
 
 import type { LogLevel } from '../types/index.js';
 import type { LogStyles } from '../types/index.js';
+import { getANSIForeground, getANSIBackground, ANSI, type ColorCapability } from './color-converter.js';
 
 export type ANSIStyle = {
     text: string;
@@ -17,32 +18,19 @@ export type ANSIStyle = {
 };
 
 export class TerminalRenderer {
-    private colorCapability: 'full' | 'basic' | 'none';
+    private colorCapability: ColorCapability;
 
-    constructor(colorCapability: 'full' | 'basic' | 'none' = 'full') {
+    constructor(colorCapability: ColorCapability = 'full') {
         this.colorCapability = colorCapability;
     }
 
     /**
-     * Get ANSI color codes for basic colors
+     * Get ANSI color codes - now supports truecolor/256-color
      */
     private getColorCode(color: string, background: boolean = false): string {
-        const colorCodes: Record<string, { normal: string; bright: string }> = {
-            'black': { normal: '30', bright: '90' },
-            'red': { normal: '31', bright: '91' },
-            'green': { normal: '32', bright: '92' },
-            'yellow': { normal: '33', bright: '93' },
-            'blue': { normal: '34', bright: '94' },
-            'magenta': { normal: '35', bright: '95' },
-            'cyan': { normal: '36', bright: '96' },
-            'white': { normal: '37', bright: '97' },
-            'gray': { normal: '90', bright: '37' },
-            'grey': { normal: '90', bright: '37' }
-        };
-
-        const codes = colorCodes[color.toLowerCase()] || { normal: '37', bright: '97' };
-        const prefix = background ? '4' : '3';
-        return `\x1b[${codes.normal}m`;
+        return background
+            ? getANSIBackground(color, this.colorCapability)
+            : getANSIForeground(color, this.colorCapability);
     }
 
     /**
@@ -207,7 +195,7 @@ export class TerminalRenderer {
     }
 
     /**
-     * Create cyberpunk-style ANSI rendering
+     * Create cyberpunk-style ANSI rendering with truecolor support
      */
     renderCyberpunk(
         level: LogLevel,
@@ -216,35 +204,36 @@ export class TerminalRenderer {
         prefix?: string,
         location?: string
     ): ANSIStyle {
-        const reset = '\x1b[0m';
-        const levelColors: Record<LogLevel, string> = {
-            'debug': '\x1b[95m', // Bright magenta
-            'info': '\x1b[94m',  // Bright blue
-            'warn': '\x1b[93m',  // Bright yellow
-            'error': '\x1b[91m', // Bright red
-            'critical': '\x1b[91m\x1b[1m' // Bright red + bold
+        const reset = ANSI.reset;
+
+        const cyberpunkColors: Record<LogLevel, string> = {
+            'debug': '#ff00ff',   // Neon magenta
+            'info': '#00ffff',    // Neon cyan
+            'warn': '#ffff00',    // Neon yellow
+            'error': '#ff0040',   // Neon red-pink
+            'critical': '#ff0000' // Pure red
         };
 
         const parts: string[] = [];
 
         if (timestamp) {
-            parts.push(`\x1b[90m${timestamp}${reset}`);
+            parts.push(`${ANSI.dim}${timestamp}${reset}`);
         }
 
-        // Cyberpunk level styling
-        const levelColor = levelColors[level] || '\x1b[97m';
-        const bgBlack = '\x1b[40m';
-        parts.push(`${bgBlack}${levelColor} ${this.getLevelText(level)} ${reset}`);
+        const levelColor = this.getColorCode(cyberpunkColors[level] || '#ffffff');
+        const bgBlack = ANSI.bg.black;
+        const bold = level === 'critical' ? ANSI.bold : '';
+        parts.push(`${bgBlack}${levelColor}${bold} ${this.getLevelText(level)} ${reset}`);
 
         if (prefix) {
-            const bgBlack = '\x1b[40m';
-            parts.push(`${bgBlack}\x1b[96m[${prefix.toUpperCase()}]${reset}`);
+            const cyanColor = this.getColorCode('#00ffff');
+            parts.push(`${bgBlack}${cyanColor}[${prefix.toUpperCase()}]${reset}`);
         }
 
         parts.push(message);
 
         if (location) {
-            parts.push(`\x1b[90m(${location})${reset}`);
+            parts.push(`${ANSI.dim}(${location})${reset}`);
         }
 
         return {
@@ -254,7 +243,7 @@ export class TerminalRenderer {
     }
 
     /**
-     * Create minimal ANSI rendering
+     * Create minimal ANSI rendering with truecolor support
      */
     renderMinimal(
         level: LogLevel,
@@ -262,26 +251,29 @@ export class TerminalRenderer {
         timestamp?: string,
         prefix?: string
     ): ANSIStyle {
-        const reset = '\x1b[0m';
-        const levelColors: Record<LogLevel, string> = {
-            'debug': '\x1b[95m', // Magenta
-            'info': '\x1b[94m',  // Blue
-            'warn': '\x1b[93m',  // Yellow
-            'error': '\x1b[91m', // Red
-            'critical': '\x1b[91m\x1b[1m' // Red + bold
+        const reset = ANSI.reset;
+
+        const minimalColors: Record<LogLevel, string> = {
+            'debug': '#c678dd', // Soft purple
+            'info': '#61afef',  // Soft blue
+            'warn': '#e5c07b',  // Soft yellow
+            'error': '#e06c75', // Soft red
+            'critical': '#be5046' // Dark red
         };
 
         const parts: string[] = [];
 
         if (timestamp) {
-            parts.push(`\x1b[90m${timestamp}${reset}`);
+            parts.push(`${ANSI.dim}${timestamp}${reset}`);
         }
 
-        const levelColor = levelColors[level] || '\x1b[97m';
-        parts.push(`${levelColor}${this.getLevelText(level)}:${reset}`);
+        const levelColor = this.getColorCode(minimalColors[level] || '#abb2bf');
+        const bold = level === 'critical' ? ANSI.bold : '';
+        parts.push(`${levelColor}${bold}${this.getLevelText(level)}:${reset}`);
 
         if (prefix) {
-            parts.push(`\x1b[96m[${prefix.toUpperCase()}]${reset}`);
+            const cyanColor = this.getColorCode('#56b6c2');
+            parts.push(`${cyanColor}[${prefix.toUpperCase()}]${reset}`);
         }
 
         parts.push(message);
@@ -293,55 +285,58 @@ export class TerminalRenderer {
     }
 
     /**
-     * Get chalk instance for log level (for compatibility with adapter)
+     * Get chalk-like interface for log level with truecolor support
      */
-    public getChalkForLevel(level: LogLevel): any {
+    public getChalkForLevel(level: LogLevel): ChalkLikeInterface {
         const levelColors: Record<LogLevel, string> = {
-            'debug': 'magenta',
-            'info': 'blue',
-            'warn': 'yellow',
-            'error': 'red',
-            'critical': 'red'
+            'debug': '#c678dd',
+            'info': '#61afef',
+            'warn': '#e5c07b',
+            'error': '#e06c75',
+            'critical': '#be5046'
         };
 
+        const reset = ANSI.reset;
+
         return {
             color: (text: string) => {
-                const color = levelColors[level] || 'white';
+                const color = levelColors[level] || '#abb2bf';
                 const colorCode = this.getColorCode(color);
-                return `${colorCode}${text}${'\x1b[0m'}`;
-            },
-            bold: (text: string) => {
-                const boldStyle = this.getStyleCode(['bold']);
-                return `${boldStyle}${text}${'\x1b[0m'}`;
-            },
-            dim: (text: string) => {
-                const dimStyle = this.getStyleCode(['dim']);
-                return `${dimStyle}${text}${'\x1b[0m'}`;
-            },
-            bgGray: (text: string) => {
-                return `\x1b[100m${text}${'\x1b[0m'}`;
-            },
-            bgBlue: (text: string) => {
-                return `\x1b[104m${text}${'\x1b[0m'}`;
+                return `${colorCode}${text}${reset}`;
             },
+            bold: (text: string) => `${ANSI.bold}${text}${reset}`,
+            dim: (text: string) => `${ANSI.dim}${text}${reset}`,
+            bgGray: (text: string) => `${ANSI.bg.gray}${text}${reset}`,
+            bgBlue: (text: string) => `${this.getColorCode('#1e3a5f', true)}${text}${reset}`,
             reset: (text: string) => text,
             cyan: {
                 bold: (text: string) => {
-                    const cyan = this.getColorCode('cyan');
-                    const bold = this.getStyleCode(['bold']);
-                    return `${cyan}${bold}${text}${'\x1b[0m'}`;
+                    const cyan = this.getColorCode('#00ffff');
+                    return `${cyan}${ANSI.bold}${text}${reset}`;
                 },
                 dim: (text: string) => {
-                    const cyan = this.getColorCode('cyan');
-                    const dim = this.getStyleCode(['dim']);
-                    return `${cyan}${dim}${text}${'\x1b[0m'}`;
+                    const cyan = this.getColorCode('#00ffff');
+                    return `${cyan}${ANSI.dim}${text}${reset}`;
                 },
                 bg: (text: string) => {
-                    const bgBlack = '\x1b[40m';
-                    const cyan = this.getColorCode('cyan');
-                    return `${bgBlack}${cyan}[${text.toUpperCase()}]${'\x1b[0m'}`;
+                    const cyan = this.getColorCode('#00ffff');
+                    return `${ANSI.bg.black}${cyan}[${text.toUpperCase()}]${reset}`;
                 }
             }
         };
     }
+}
+
+export interface ChalkLikeInterface {
+    color: (text: string) => string;
+    bold: (text: string) => string;
+    dim: (text: string) => string;
+    bgGray: (text: string) => string;
+    bgBlue: (text: string) => string;
+    reset: (text: string) => string;
+    cyan: {
+        bold: (text: string) => string;
+        dim: (text: string) => string;
+        bg: (text: string) => string;
+    };
 }

package/src/types/core.ts

@@ -100,6 +100,48 @@ export type ExportFormat = 'json' | 'csv' | 'markdown' | 'plain' | 'html';
  */
 export type OutputFormat = 'auto' | 'plain' | 'ansi' | 'build' | 'ci';
 
+/**
+ * Output modes for controlling where logs are written
+ * @typedef {'console' | 'silent' | 'custom'} OutputMode
+ *
+ * @description
+ * - console: Standard console.log output (default)
+ * - silent: No output at all
+ * - custom: Use custom OutputWriter for advanced scenarios
+ */
+export type OutputMode = 'console' | 'silent' | 'custom';
+
+/**
+ * Custom output writer interface for redirecting log output
+ *
+ * @interface OutputWriter
+ * @since 4.0.0
+ *
+ * @description
+ * Allows redirecting log output to custom destinations like:
+ * - DraftLog for CLI spinners with concurrent logging
+ * - Buffers for collecting logs during operations
+ * - Custom streams or transports
+ *
+ * @example
+ * class BufferWriter implements OutputWriter {
+ *   private buffer: string[] = [];
+ *
+ *   write(message: string, level: LogLevel, styles: string[]): void {
+ *     this.buffer.push(message);
+ *   }
+ *
+ *   flush(): void {
+ *     this.buffer.forEach(msg => console.log(msg));
+ *     this.buffer = [];
+ *   }
+ * }
+ */
+export interface OutputWriter {
+    write(message: string, level: LogLevel, styles: string[]): void;
+    flush?(): void;
+}
+
 /**
  * Interfaz de configuración para instancias del logger
  * 
@@ -130,6 +172,10 @@ export interface LoggerConfig {
     bufferSize?: number;
     autoDetectTheme?: boolean;
     outputFormat?: OutputFormat;
+    /** Output mode: 'console' (default), 'silent', or 'custom' @since 4.0.0 */
+    outputMode?: OutputMode;
+    /** Custom writer when outputMode is 'custom' @since 4.0.0 */
+    outputWriter?: OutputWriter;
 }
 
 /**
@@ -293,4 +339,26 @@ export interface Bindings {
     badges?: string[];
     type?: 'scope' | 'api' | 'component';
     context?: string[];
+}
+
+export type BadgeStyle = 'brackets' | 'rounded' | 'plain' | 'unicode' | 'pill';
+
+export type TimestampFormat = 'iso' | 'time' | 'timeMs' | 'relative' | 'elapsed' | 'date' | 'custom';
+
+export type ColumnAlign = 'left' | 'right' | 'center';
+
+export interface ColumnConfig {
+    content: string;
+    width?: number;
+    align?: ColumnAlign;
+    color?: string;
+}
+
+export interface LogOptions {
+    rightAlign?: string;
+    columns?: ColumnConfig[];
+    maxWidth?: number;
+    keyValue?: boolean;
+    badgeStyle?: BadgeStyle;
+    timestampFormat?: TimestampFormat;
 }

package/src/types/index.ts

@@ -25,6 +25,11 @@ export type {
     IAPILogger,
     IComponentLogger,
     Bindings,
+    BadgeStyle,
+    TimestampFormat,
+    ColumnAlign,
+    ColumnConfig,
+    LogOptions,
 } from './core.js';
 
 export { LOG_LEVELS } from './core.js';

package/src/utils/environment-detector.ts

@@ -131,6 +131,26 @@ export function getColorCapability(): 'full' | 'basic' | 'none' {
     return 'basic'; // Basic 16 colors
 }
 
+/**
+ * Get terminal width in columns
+ */
+export function getTerminalWidth(): number {
+    if (typeof process !== 'undefined' && process.stdout?.columns) {
+        return process.stdout.columns;
+    }
+    return 80;
+}
+
+/**
+ * Get terminal height in rows
+ */
+export function getTerminalHeight(): number {
+    if (typeof process !== 'undefined' && process.stdout?.rows) {
+        return process.stdout.rows;
+    }
+    return 24;
+}
+
 /**
  * Environment information for debugging
  */
@@ -143,6 +163,8 @@ export function getEnvironmentInfo() {
         platform: typeof process !== 'undefined' ? process.platform : 'unknown',
         nodeVersion: typeof process !== 'undefined' ? process.versions?.node : null,
         term: typeof process !== 'undefined' ? process.env?.TERM : null,
-        colorTerm: typeof process !== 'undefined' ? process.env?.COLORTERM : null
+        colorTerm: typeof process !== 'undefined' ? process.env?.COLORTERM : null,
+        terminalWidth: getTerminalWidth(),
+        terminalHeight: getTerminalHeight()
     };
 }