logan-logger 1.0.2 → 1.1.0

package/dist/bun.d.ts

@@ -0,0 +1,323 @@
+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;
+}
+
+/**
+ * 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;
+
+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;
+}
+
+/**
+ * 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>>;
+
+/**
+ * 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 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;
+}
+
+/**
+ * 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/bun.esm.js

@@ -0,0 +1,21 @@
+import { N as o, a as r, c as s, e as i, p as t, j as n, f as g, h as f, g as m, i as l, k as d, m as L, n as c, o as v, q as C } from "./node-BqvVrzA_.mjs";
+import { formatLevel as F, formatLogEntry as p } from "./deno.esm.js";
+export {
+  o as NodeLogger,
+  r as createLogger,
+  s as createLoggerForEnvironment,
+  i as detectRuntime,
+  t as filterSensitiveData,
+  F as formatLevel,
+  p as formatLogEntry,
+  n as getDefaultConfig,
+  g as isBrowser,
+  f as isBun,
+  m as isDeno,
+  l as isNode,
+  d as loadConfigFromEnvironment,
+  L as loadConfigFromFile,
+  c as mergeConfigs,
+  v as safeStringify,
+  C as serializeError
+};

package/dist/bun.js

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

package/dist/deno.d.ts

@@ -0,0 +1,343 @@
+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;
+
+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;
+}
+
+/**
+ * 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>>;
+
+/**
+ * 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 function mergeConfigs(...configs: Partial<LoggerConfig>[]): LoggerConfig;
+
+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 { }