logan-logger 1.0.2 → 1.1.1

package/README.md

@@ -1,6 +1,7 @@
 # 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)
+[![npm](https://img.shields.io/npm/v/logan-logger)](https://www.npmjs.com/package/logan-logger)
 [![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.
@@ -19,11 +20,17 @@ A universal TypeScript logging library that works consistently across all JavaSc
 ## Quick Start
 
 ```bash
+# NPM
 npm install logan-logger
 # or
 pnpm add logan-logger
 # or
 yarn add logan-logger
+
+# JSR (Deno/Node.js)
+deno add @logan/logger
+# or
+npx jsr add @logan/logger
 ```
 
 ### Basic Usage
@@ -70,11 +77,13 @@ const logger = createLoggerForEnvironment();
 // Test: WARN level
 ```
 
-#### Runtime-Specific Features
+#### Runtime-Specific Imports
 
-**Node.js with Winston:**
+Logan Logger provides runtime-specific entry points for optimal bundling and type safety:
+
+**🟢 Node.js with Winston Support:**
 ```typescript
-import { NodeLogger, createMorganStream } from 'logan-logger';
+import { createLogger, NodeLogger, createMorganStream } from 'logan-logger/node';
 
 const logger = new NodeLogger({
   transports: [
@@ -86,9 +95,9 @@ const logger = new NodeLogger({
 app.use(morgan('combined', { stream: createMorganStream(logger) }));
 ```
 
-**Browser with Performance:**
+**🌐 Browser-Optimized (Webpack/Vite-Safe):**
 ```typescript
-import { PerformanceLogger } from 'logan-logger';
+import { createLogger, BrowserLogger, PerformanceLogger } from 'logan-logger/browser';
 
 const logger = new PerformanceLogger();
 
@@ -97,6 +106,30 @@ logger.mark('api-start');
 logger.measure('api-duration', 'api-start');
 ```
 
+**🦕 Deno-Optimized:**
+```typescript
+import { createLogger, BrowserLogger } from 'logan-logger/deno';
+
+const logger = createLogger({ colorize: true });
+logger.info('Deno application started');
+```
+
+**🥟 Bun-Optimized:**
+```typescript
+import { createLogger, NodeLogger } from 'logan-logger/bun';
+
+const logger = createLogger({ level: LogLevel.DEBUG });
+logger.info('Bun application started');
+```
+
+**🔧 Auto-Detection (Generic):**
+```typescript
+import { createLogger } from 'logan-logger';
+
+// Automatically selects appropriate logger based on runtime
+const logger = createLogger();
+```
+
 #### Safe Data Handling
 ```typescript
 import { filterSensitiveData } from 'logan-logger';
@@ -113,16 +146,16 @@ logger.info('User processed', safeData);
 // Logs: { name: 'John Doe', email: 'john@example.com', password: '[REDACTED]', apiKey: '[REDACTED]' }
 ```
 
-## Runtime Support
+## Runtime Support & Import Paths
 
-| 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 |
+| Runtime | Import Path | Status | Implementation | Features |
+|---------|-------------|--------|----------------|----------|
+| 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 |
+| Deno | `@logan/logger/deno` (JSR) | ✅ Basic | BrowserLogger adapter | Console logging (native implementation planned) |
+| WebWorker | `logan-logger/browser` | ✅ Basic | Console adapter | Basic console logging |
+| Auto-detect | `logan-logger` | ✅ Basic | Runtime detection | Automatic adapter selection |
 
 ## Configuration
 

package/dist/browser.d.ts

@@ -0,0 +1,335 @@
+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;
+}
+
+/**
+ * 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;
+
+/**
+ * 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;
+
+/**
+ * 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;
+}
+
+/**
+ * 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 { }

package/dist/browser.esm.js

@@ -0,0 +1,19 @@
+import { B as o, C as a, P as s, a as t, c as i, e as g, p as n, f, h as m, g as L, i as c, o as l, q as p } from "./node-BqvVrzA_.mjs";
+import { formatLevel as u, formatLogEntry as v } from "./deno.esm.js";
+export {
+  o as BrowserLogger,
+  a as ConsoleGroupLogger,
+  s as PerformanceLogger,
+  t as createLogger,
+  i as createLoggerForEnvironment,
+  g as detectRuntime,
+  n as filterSensitiveData,
+  u as formatLevel,
+  v as formatLogEntry,
+  f as isBrowser,
+  m as isBun,
+  L as isDeno,
+  c as isNode,
+  l as safeStringify,
+  p as serializeError
+};

package/dist/browser.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./node-BKsollr4.js"),r=require("./deno.js");exports.BrowserLogger=e.BrowserLogger;exports.ConsoleGroupLogger=e.ConsoleGroupLogger;exports.PerformanceLogger=e.PerformanceLogger;exports.createLogger=e.createLogger;exports.createLoggerForEnvironment=e.createLoggerForEnvironment;exports.detectRuntime=e.detectRuntime;exports.filterSensitiveData=e.filterSensitiveData;exports.isBrowser=e.isBrowser;exports.isBun=e.isBun;exports.isDeno=e.isDeno;exports.isNode=e.isNode;exports.safeStringify=e.safeStringify;exports.serializeError=e.serializeError;exports.formatLevel=r.formatLevel;exports.formatLogEntry=r.formatLogEntry;