logan-logger 1.1.3 → 1.1.7

package/README.md

@@ -9,6 +9,7 @@ A universal TypeScript logging library that works consistently across all JavaSc
 ## Features
 
 - 🌐 **Universal Runtime Support** - Works in Node.js, Deno, Bun, browsers, and WebAssembly
+- ⚛️ **Next.js Ready** - Full compatibility with App Router, Server Components, and API Routes
 - 🪶 **Zero Dependencies** - Core functionality with no required dependencies
 - ⚡ **Performance First** - Lazy evaluation, zero-allocation logging, minimal memory footprint
 - 🎯 **TypeScript Native** - Full type safety with comprehensive type definitions
@@ -58,6 +59,91 @@ const requestLogger = logger.child({
 requestLogger.info('Processing request', { endpoint: '/api/users' });
 ```
 
+### Next.js Integration
+
+Logan Logger is fully compatible with Next.js 13+ App Router, including Server Components, Client Components, and API Routes.
+
+#### Server Components
+```typescript
+import { createLogger, LogLevel } from 'logan-logger';
+
+const logger = createLogger({
+  level: process.env.NODE_ENV === 'development' ? LogLevel.DEBUG : LogLevel.INFO,
+  format: 'json'
+});
+
+export default async function ServerComponent() {
+  logger.info('Server component rendered');
+  
+  // Server-side data fetching
+  const data = await fetchData();
+  logger.debug('Data fetched', { recordCount: data.length });
+  
+  return <div>Server content</div>;
+}
+```
+
+#### Client Components
+```typescript
+'use client';
+
+import { createLogger, LogLevel } from 'logan-logger';
+
+const logger = createLogger({
+  level: LogLevel.INFO,
+  colorize: true
+});
+
+export default function ClientComponent() {
+  const handleClick = () => {
+    logger.info('User interaction', { action: 'button_click' });
+  };
+
+  return <button onClick={handleClick}>Click me</button>;
+}
+```
+
+#### API Routes
+```typescript
+// app/api/users/route.ts
+import { NextResponse } from 'next/server';
+import { createLogger } from 'logan-logger';
+
+const logger = createLogger({
+  format: 'json',
+  metadata: { service: 'api' }
+});
+
+export async function GET() {
+  const start = Date.now();
+  logger.info('API request started', { endpoint: '/api/users' });
+  
+  try {
+    const users = await getUsers();
+    const duration = Date.now() - start;
+    
+    logger.info('API request completed', { 
+      statusCode: 200, 
+      duration,
+      userCount: users.length 
+    });
+    
+    return NextResponse.json(users);
+  } catch (error) {
+    const duration = Date.now() - start;
+    logger.error('API request failed', { 
+      statusCode: 500, 
+      duration,
+      error: error instanceof Error ? error.message : 'Unknown error'
+    });
+    
+    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 });
+  }
+}
+```
+
+> **📋 See [Next.js Compatibility Guide](./docs/nextjs-compatibility.md) for complete setup instructions, advanced patterns, and troubleshooting.**
+
 ### Advanced Features
 
 #### Lazy Evaluation for Performance
@@ -150,6 +236,7 @@ logger.info('User processed', safeData);
 
 | Runtime | Import Path | Status | Implementation | Features |
 |---------|-------------|--------|----------------|----------|
+| **Next.js 13+** | `logan-logger` | ✅ **Full** | **Auto-detection** | **Server/Client Components, API Routes, Edge Runtime** |
 | Node.js 20+ | `logan-logger/node` | ✅ Full | Winston + Console | File logging, transports, Morgan integration |
 | Bun | `logan-logger/bun` | ✅ Full | NodeLogger adapter | Same as Node.js |
 | Browser | `logan-logger/browser` | ✅ Full | Console API | CSS styling, performance marks, grouping |

package/dist/browser.d.ts

@@ -1,331 +1,25 @@
-declare abstract class BaseLogger implements ILogger {
-    protected level: LogLevel;
-    protected config: Partial<LoggerConfig>;
-    protected runtime: RuntimeName;
-    protected childMetadata: Record<string, any>;
-    protected constructor(config?: Partial<LoggerConfig>);
-    debug(message: LogMessage, metadata?: any): void;
-    info(message: LogMessage, metadata?: any): void;
-    warn(message: LogMessage, metadata?: any): void;
-    error(message: LogMessage, metadata?: any): void;
-    log(level: LogLevel, message: LogMessage, metadata?: any): void;
-    setLevel(level: LogLevel): void;
-    getLevel(): LogLevel;
-    child(metadata: Record<string, any>): ILogger;
-    protected shouldLog(level: LogLevel): boolean;
-    protected abstract writeLog(entry: LogEntry): void;
-    protected abstract createChild(): BaseLogger;
-}
-
-export declare class BrowserLogger extends BaseLogger {
-    constructor(config?: Partial<LoggerConfig>);
-    protected writeLog(entry: LogEntry): void;
-    protected createChild(): BaseLogger;
-    private formatMessage;
-    private getConsoleStyle;
-    private shouldLogInProduction;
-    protected shouldLog(level: LogLevel): boolean;
-}
-
-export declare class ConsoleGroupLogger extends BrowserLogger {
-    private groupStack;
-    group(label: string): void;
-    groupCollapsed(label: string): void;
-    groupEnd(): void;
-    getCurrentGroupStack(): string[];
-    getCurrentGroupPath(): string;
-    time(label: string): void;
-    timeEnd(label: string): void;
-    trace(message: string, metadata?: any): void;
-    count(label?: string): void;
-    countReset(label?: string): void;
-    table(data: any): void;
-}
-
-/**
- * Browser-specific logger factory function.
- * Creates a BrowserLogger instance without importing Node.js dependencies.
- */
-export declare function createLogger(config?: Partial<LoggerConfig>): ILogger;
-
-/**
- * Create a browser logger with configuration based on the current environment.
- * Automatically detects production/development/test environments and
- * sets appropriate log levels and formatting.
- */
-export declare function createLoggerForEnvironment(): ILogger;
-
-/**
- * Detects the current JavaScript runtime environment and its capabilities.
- * @returns Information about the detected runtime
- * @example
- * ```typescript
- * const runtime = detectRuntime();
- * console.log(`Running on: ${runtime.name} ${runtime.version}`);
- * ```
- */
-export declare function detectRuntime(): RuntimeInfo;
-
-/**
- * Filter out sensitive data from an object before logging.
- * @param obj - The object to filter
- * @param sensitiveKeys - Array of key names to redact (case-insensitive)
- * @returns A new object with sensitive values replaced with '[REDACTED]'
- * @example
- * ```typescript
- * const data = { username: 'john', password: 'secret123' };
- * const filtered = filterSensitiveData(data);
- * // Result: { username: 'john', password: '[REDACTED]' }
- * ```
- */
-export declare function filterSensitiveData(obj: any, sensitiveKeys?: string[]): any;
-
-/**
- * Format log level as a colored string for terminal output.
- * @param level - The log level to format
- * @param colorize - Whether to apply ANSI color codes
- * @returns Formatted level string with optional colors
- */
-export declare function formatLevel(level: LogLevel, colorize?: boolean): string;
-
-/**
- * Format a log entry for output in different formats.
- * @param entry - The log entry to format
- * @param format - Output format ('json' or 'text')
- * @returns Formatted log string
- * @example
- * ```typescript
- * const entry: LogEntry = {
- *   timestamp: new Date(),
- *   level: LogLevel.INFO,
- *   message: 'User logged in',
- *   metadata: { userId: 123 },
- *   runtime: 'node'
- * };
- *
- * const textFormat = formatLogEntry(entry, 'text');
- * // Result: "[2024-01-01T12:00:00.000Z] INFO: User logged in {\"userId\":123}"
- *
- * const jsonFormat = formatLogEntry(entry, 'json');
- * // Result: {"timestamp":"2024-01-01T12:00:00.000Z","level":"info","message":"User logged in","metadata":{"userId":123},"runtime":"node"}
- * ```
- */
-export declare function formatLogEntry(entry: LogEntry, format?: 'json' | 'text'): string;
-
-/**
- * Main logger interface providing methods for logging at different levels.
- * This interface is implemented by all logger implementations across different runtimes.
- */
-export declare interface ILogger {
-    /**
-     * Log a debug message. Only shown when log level is DEBUG.
-     * @param message - The message to log (string or lazy function)
-     * @param metadata - Optional structured data to include
-     */
-    debug(message: LogMessage, metadata?: any): void;
-    /**
-     * Log an informational message.
-     * @param message - The message to log (string or lazy function)
-     * @param metadata - Optional structured data to include
-     */
-    info(message: LogMessage, metadata?: any): void;
-    /**
-     * Log a warning message.
-     * @param message - The message to log (string or lazy function)
-     * @param metadata - Optional structured data to include
-     */
-    warn(message: LogMessage, metadata?: any): void;
-    /**
-     * Log an error message.
-     * @param message - The message to log (string or lazy function)
-     * @param metadata - Optional structured data to include
-     */
-    error(message: LogMessage, metadata?: any): void;
-    /**
-     * Log a message at a specific level.
-     * @param level - The log level
-     * @param message - The message to log (string or lazy function)
-     * @param metadata - Optional structured data to include
-     */
-    log(level: LogLevel, message: LogMessage, metadata?: any): void;
-    /**
-     * Set the minimum log level for this logger.
-     * @param level - The minimum log level
-     */
-    setLevel(level: LogLevel): void;
-    /**
-     * Get the current minimum log level.
-     * @returns The current log level
-     */
-    getLevel(): LogLevel;
-    /**
-     * Create a child logger with additional metadata.
-     * @param metadata - Additional metadata to include in all child log messages
-     * @returns A new logger instance with the additional metadata
-     */
-    child(metadata: Record<string, any>): ILogger;
-}
-
-/**
- * Check if the current runtime is a browser.
- * @returns True if running in a browser
- */
-export declare function isBrowser(): boolean;
-
-/**
- * Check if the current runtime is Bun.
- * @returns True if running in Bun
- */
-export declare function isBun(): boolean;
-
-/**
- * Check if the current runtime is Deno.
- * @returns True if running in Deno
- */
-export declare function isDeno(): boolean;
-
-/**
- * Check if the current runtime is Node.js.
- * @returns True if running in Node.js
- */
-export declare function isNode(): boolean;
-
-export declare const log: {
-    debug: (message: string, meta?: any) => void;
-    info: (message: string, meta?: any) => void;
-    warn: (message: string, meta?: any) => void;
-    error: (message: string, meta?: any) => void;
-};
-
-/**
- * Internal representation of a log entry.
- */
-declare interface LogEntry {
-    /** When the log entry was created */
-    timestamp: Date;
-    /** Log level of this entry */
-    level: LogLevel;
-    /** The log message */
-    message: string;
-    /** Additional structured data */
-    metadata?: Record<string, any>;
-    /** Runtime that generated this log entry */
-    runtime: RuntimeName;
-}
-
-export declare const logger: ILogger;
-
-/**
- * Configuration options for creating a logger instance.
- */
-export declare interface LoggerConfig {
-    /** Minimum log level to output */
-    level: LogLevel;
-    /** Output format for log messages */
-    format: 'json' | 'text' | 'custom';
-    /** Whether to include timestamps in log output */
-    timestamp: boolean;
-    /** Whether to colorize log output (if supported) */
-    colorize: boolean;
-    /** Default metadata to include with all log messages */
-    metadata: Record<string, any>;
-    /** Transport configurations for log output */
-    transports?: TransportConfig[];
-}
-
-/**
- * Log levels in ascending order of severity.
- * Used to filter which messages should be logged.
- */
-export declare enum LogLevel {
-    /** Debug messages - most verbose */
-    DEBUG = 0,
-    /** Informational messages */
-    INFO = 1,
-    /** Warning messages */
-    WARN = 2,
-    /** Error messages */
-    ERROR = 3,
-    /** No messages - silent mode */
-    SILENT = 4
-}
-
-/**
- * A log message can be a string or a function that returns a string.
- * Functions enable lazy evaluation for expensive log message generation.
- */
-declare type LogMessage = string | (() => string);
-
-export declare class PerformanceLogger extends BrowserLogger {
-    mark(name: string): void;
-    measure(name: string, startMark?: string, endMark?: string): void;
-    clearMarks(name?: string): void;
-    clearMeasures(name?: string): void;
-}
-
-/**
- * Capabilities that a runtime may or may not support.
- */
-declare interface RuntimeCapabilities {
-    /** Whether the runtime supports file system operations */
-    fileSystem: boolean;
-    /** Whether the runtime supports colored console output */
-    colorSupport: boolean;
-    /** Whether the runtime provides process information */
-    processInfo: boolean;
-    /** Whether the runtime supports streams */
-    streams: boolean;
-}
-
-/**
- * Information about the detected JavaScript runtime environment.
- */
-declare interface RuntimeInfo {
-    /** The name of the runtime */
-    name: RuntimeName;
-    /** Version string of the runtime (if available) */
-    version?: string;
-    /** Capabilities supported by this runtime */
-    capabilities: RuntimeCapabilities;
-}
-
-/**
- * Supported JavaScript runtime environments.
- */
-declare type RuntimeName = 'node' | 'deno' | 'bun' | 'browser' | 'webworker' | 'unknown';
-
-/**
- * Safely stringify an object to JSON, handling circular references,
- * Error objects, functions, and other non-serializable values.
- * @param obj - The object to stringify
- * @param space - Number of spaces for pretty-printing (optional)
- * @returns JSON string representation
- */
-export declare function safeStringify(obj: any, space?: number): string;
-
-/**
- * Serialize Error objects to plain objects for logging.
- * @param error - The error to serialize
- * @returns Serialized error object or original value if not an Error
- * @example
- * ```typescript
- * const error = new Error('Something went wrong');
- * const serialized = serializeError(error);
- * // Result: { name: 'Error', message: 'Something went wrong', stack: '...' }
- * ```
- */
-export declare function serializeError(error: any): any;
-
-/**
- * Configuration for a specific log transport (output destination).
- */
-declare interface TransportConfig {
-    /** Type of transport */
-    type: 'console' | 'file' | 'http' | 'custom';
-    /** Minimum log level for this transport */
-    level?: LogLevel;
-    /** Transport-specific options */
-    options: Record<string, any>;
-}
-
-export { }
+import { LoggerConfig, ILogger } from './core/types';
+export { BrowserLogger, ConsoleGroupLogger, PerformanceLogger } from './runtime/browser';
+export type { ILogger, LoggerConfig } from './core/types';
+export { LogLevel } from './core/types';
+export * from './utils/runtime';
+export * from './utils/serialization';
+export * from './utils/formatting';
+/**
+ * Browser-specific logger factory function.
+ * Creates a BrowserLogger instance without importing Node.js dependencies.
+ */
+export declare function createLogger(config?: Partial<LoggerConfig>): ILogger;
+/**
+ * Create a browser logger with configuration based on the current environment.
+ * Automatically detects production/development/test environments and
+ * sets appropriate log levels and formatting.
+ */
+export declare function createLoggerForEnvironment(): ILogger;
+export declare const logger: ILogger;
+export declare const log: {
+    debug: (message: string, meta?: any) => void;
+    info: (message: string, meta?: any) => void;
+    warn: (message: string, meta?: any) => void;
+    error: (message: string, meta?: any) => void;
+};