logan-logger 1.0.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Logan Lindquist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,245 @@
+# Logan Logger
+
+[![CI](https://github.com/llbbl/logan-logger-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/llbbl/logan-logger-ts/actions/workflows/ci.yml)
+[![JSR](https://jsr.io/badges/@logan/logger)](https://jsr.io/@logan/logger)
+
+A universal TypeScript logging library that works consistently across all JavaScript runtimes: Node.js, Deno, Bun, browsers, and WebAssembly environments.
+
+## Features
+
+- 🌐 **Universal Runtime Support** - Works in Node.js, Deno, Bun, browsers, and WebAssembly
+- 🪶 **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
+- 🔧 **Flexible Configuration** - Environment-based auto-configuration or manual setup
+- 🔒 **Safe Serialization** - Handles circular references, Error objects, and sensitive data filtering
+- 🎨 **Rich Browser Support** - Console styling, performance marks, grouping
+- 📊 **Structured Logging** - Rich metadata support with child loggers
+
+## Quick Start
+
+```bash
+npm install logan-logger
+# or
+pnpm add logan-logger
+# or
+yarn add logan-logger
+```
+
+### Basic Usage
+
+```typescript
+import { createLogger, LogLevel } from 'logan-logger';
+
+// Create logger with automatic environment configuration
+const logger = createLogger({
+  level: LogLevel.DEBUG,
+  colorize: true
+});
+
+// Basic logging
+logger.info('Application started');
+logger.warn('Configuration missing', { file: 'config.json' });
+logger.error('Database connection failed', { error: new Error('Connection failed') });
+
+// Child loggers with additional context
+const requestLogger = logger.child({ 
+  requestId: 'req-123', 
+  userId: 'user-456' 
+});
+
+requestLogger.info('Processing request', { endpoint: '/api/users' });
+```
+
+### Advanced Features
+
+#### Lazy Evaluation for Performance
+```typescript
+// Function is only called if debug level is enabled
+logger.debug(() => `Expensive computation: ${computeHeavyValue()}`);
+```
+
+#### Environment-Based Configuration
+```typescript
+import { createLoggerForEnvironment } from 'logan-logger';
+
+// Automatically configures based on NODE_ENV
+const logger = createLoggerForEnvironment();
+// Production: ERROR level, JSON format
+// Development: DEBUG level, colored console
+// Test: WARN level
+```
+
+#### Runtime-Specific Features
+
+**Node.js with Winston:**
+```typescript
+import { NodeLogger, createMorganStream } from 'logan-logger';
+
+const logger = new NodeLogger({
+  transports: [
+    { type: 'file', options: { filename: 'app.log' } }
+  ]
+});
+
+// Express/Morgan integration
+app.use(morgan('combined', { stream: createMorganStream(logger) }));
+```
+
+**Browser with Performance:**
+```typescript
+import { PerformanceLogger } from 'logan-logger';
+
+const logger = new PerformanceLogger();
+
+logger.mark('api-start');
+// ... API call
+logger.measure('api-duration', 'api-start');
+```
+
+#### Safe Data Handling
+```typescript
+import { filterSensitiveData } from 'logan-logger';
+
+const userData = {
+  name: 'John Doe',
+  email: 'john@example.com',
+  password: 'secret123',  // Will be filtered
+  apiKey: 'sk_live_...'   // Will be filtered
+};
+
+const safeData = filterSensitiveData(userData);
+logger.info('User processed', safeData);
+// Logs: { name: 'John Doe', email: 'john@example.com', password: '[REDACTED]', apiKey: '[REDACTED]' }
+```
+
+## Runtime Support
+
+| Runtime | Status | Implementation | Features |
+|---------|--------|----------------|----------|
+| Node.js 20+ | ✅ Full | Winston + Console | File logging, transports, Morgan integration |
+| Bun | ✅ Full | Node.js adapter | Same as Node.js |
+| Browser | ✅ Full | Console API | CSS styling, performance marks, grouping |
+| Deno | ✅ Basic | Console adapter | Console logging (native implementation planned) |
+| WebWorker | ✅ Basic | Console adapter | Basic console logging |
+| WebAssembly | ✅ Basic | Console adapter | Message passing to host |
+
+## Configuration
+
+### Log Levels
+```typescript
+enum LogLevel {
+  DEBUG = 0,    // Most verbose
+  INFO = 1,     // General information  
+  WARN = 2,     // Warning messages
+  ERROR = 3,    // Error messages
+  SILENT = 4    // No output
+}
+```
+
+### Environment Variables
+```bash
+LOG_LEVEL=debug      # debug, info, warn, error, silent
+LOG_FORMAT=json      # json, text
+LOG_TIMESTAMP=true   # true, false
+LOG_COLOR=false      # true, false
+```
+
+> **📋 See [Environment Variables Documentation](./docs/environment-variables.md) for complete details, examples, and runtime-specific considerations.**
+
+### Configuration Options
+```typescript
+interface LoggerConfig {
+  level: LogLevel;
+  format: 'json' | 'text' | 'custom';
+  timestamp: boolean;
+  colorize: boolean;
+  metadata: Record<string, any>;
+  transports?: TransportConfig[];
+}
+```
+
+## API Reference
+
+### Core Methods
+```typescript
+interface ILogger {
+  debug(message: string | (() => string), metadata?: any): void;
+  info(message: string | (() => string), metadata?: any): void;
+  warn(message: string | (() => string), metadata?: any): void;
+  error(message: string | (() => string), metadata?: any): void;
+  
+  setLevel(level: LogLevel): void;
+  getLevel(): LogLevel;
+  child(metadata: Record<string, any>): ILogger;
+}
+```
+
+### Factory Functions
+```typescript
+// Create logger with explicit configuration
+createLogger(config?: Partial<LoggerConfig>): ILogger;
+
+// Create logger based on environment
+createLoggerForEnvironment(): ILogger;
+```
+
+## Development
+
+### Setup
+```bash
+git clone <repository>
+cd logan-logger-ts
+pnpm install
+```
+
+### Commands
+```bash
+# Development
+pnpm dev                    # Run with bun
+pnpm test                   # Test watch mode
+pnpm test:run              # Single test run
+pnpm test:ui               # Test UI
+
+# Building
+pnpm build                 # Full build
+pnpm typecheck            # Type checking
+pnpm lint                  # Code linting
+
+# Specific tests
+vitest run tests/logger.test.ts
+```
+
+## Architecture
+
+Logan Logger uses a **Factory + Adapter pattern**:
+
+1. **Runtime Detection** - Automatically detects the current JavaScript environment
+2. **Factory Creation** - Creates the appropriate logger implementation
+3. **Runtime Adapters** - Optimized implementations for each environment
+4. **Unified Interface** - Consistent API across all runtimes
+
+### File Structure
+```
+src/
+├── core/           # Core interfaces and factory
+├── runtime/        # Runtime-specific implementations  
+├── utils/          # Utilities (serialization, config, runtime detection)
+└── index.ts        # Main exports
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass: `pnpm test:run`
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Credits
+
+Created by Logan Lindquist Land

package/dist/__vite-browser-external-BcPniuRQ.js

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e={};exports.default=e;
+//# sourceMappingURL=__vite-browser-external-BcPniuRQ.js.map

package/dist/__vite-browser-external-BcPniuRQ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"__vite-browser-external-BcPniuRQ.js","sources":["../__vite-browser-external"],"sourcesContent":["export default {}"],"names":["__viteBrowserExternal"],"mappings":"gFAAA,MAAAA,EAAe,CAAA"}

package/dist/__vite-browser-external-DYxpcVy9.mjs

@@ -0,0 +1,5 @@
+const e = {};
+export {
+  e as default
+};
+//# sourceMappingURL=__vite-browser-external-DYxpcVy9.mjs.map

package/dist/__vite-browser-external-DYxpcVy9.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"__vite-browser-external-DYxpcVy9.mjs","sources":["../__vite-browser-external"],"sourcesContent":["export default {}"],"names":["__viteBrowserExternal"],"mappings":"AAAA,MAAAA,IAAe,CAAA;"}

package/dist/index.d.ts

@@ -0,0 +1,376 @@
+export declare abstract class BaseLogger implements ILogger {
+    protected level: LogLevel;
+    protected config: Partial<LoggerConfig>;
+    protected runtime: RuntimeName;
+    protected childMetadata: Record<string, any>;
+    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;
+    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;
+}
+
+/**
+ * Convenience function for creating a logger instance.
+ * @param config - Optional configuration for the logger
+ * @returns A logger instance appropriate for the current runtime
+ * @example
+ * ```typescript
+ * import { createLogger, LogLevel } from 'logan-logger';
+ *
+ * const logger = createLogger({
+ *   level: LogLevel.DEBUG,
+ *   colorize: true
+ * });
+ *
+ * logger.info('Hello world!');
+ * ```
+ */
+export declare function createLogger(config?: Partial<LoggerConfig>): ILogger;
+
+/**
+ * Create a logger with configuration based on the current environment.
+ * Automatically detects production/development/test environments and
+ * sets appropriate log levels and formatting.
+ * @returns A logger instance configured for the current environment
+ */
+export declare function createLoggerForEnvironment(): ILogger;
+
+export declare function createMorganStream(logger: NodeLogger): {
+    write: (message: string) => void;
+};
+
+/**
+ * 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;
+
+export declare function formatLogEntry(entry: LogEntry, format?: 'json' | 'text'): string;
+
+export declare function getDefaultConfig(): LoggerConfig;
+
+/**
+ * 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;
+}
+
+/**
+ * Interface for logger adapters that handle the actual log output.
+ * This abstraction allows different implementations for different runtimes.
+ */
+export declare interface ILoggerAdapter {
+    /**
+     * Write a log entry to the output destination.
+     * @param entry - The log entry to write
+     */
+    log(entry: LogEntry): void;
+    /**
+     * Set the minimum log level for this adapter.
+     * @param level - The minimum log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Get the current minimum log level.
+     * @returns The current log level
+     */
+    getLevel(): LogLevel;
+}
+
+/**
+ * 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 function loadConfigFromEnvironment(): Partial<LoggerConfig>;
+
+export declare function loadConfigFromFile(configPath?: string): Promise<Partial<LoggerConfig>>;
+
+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.
+ */
+export 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[];
+}
+
+/**
+ * Factory class for creating logger instances based on the detected runtime.
+ */
+export declare class LoggerFactory {
+    /**
+     * Create a logger instance appropriate for the current runtime.
+     * @param config - Optional configuration for the logger
+     * @returns A logger instance
+     */
+    static create(config?: Partial<LoggerConfig>): ILogger;
+    /**
+     * Create a child logger with additional metadata.
+     * @param parent - The parent logger instance
+     * @param metadata - Additional metadata to include in all child log messages
+     * @returns A new logger instance with the additional metadata
+     */
+    static createChild(parent: ILogger, metadata: Record<string, any>): ILogger;
+    private static mergeConfig;
+}
+
+/**
+ * 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
+}
+
+/**
+ * String representation of log levels.
+ */
+export declare type LogLevelString = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+
+export declare function logLevelToString(level: LogLevel): string;
+
+/**
+ * A log message can be a string or a function that returns a string.
+ * Functions enable lazy evaluation for expensive log message generation.
+ */
+export declare type LogMessage = string | (() => string);
+
+export declare function mergeConfigs(...configs: Partial<LoggerConfig>[]): LoggerConfig;
+
+export declare class NodeLogger extends BaseLogger {
+    private winston?;
+    constructor(config?: Partial<LoggerConfig>);
+    private initializeWinston;
+    private createWinstonLogger;
+    protected writeLog(entry: LogEntry): void;
+    protected createChild(): BaseLogger;
+    private writeToConsole;
+    private getWinstonLevel;
+    setLevel(level: LogLevel): void;
+}
+
+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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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;
+
+export declare function serializeError(error: any): any;
+
+export declare function stringToLogLevel(level: string): LogLevel;
+
+/**
+ * Configuration for a specific log transport (output destination).
+ */
+export 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 { }