@feizk/logger 1.7.0 → 2.0.1

package/dist/index.d.ts

@@ -1,86 +1,239 @@
-type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-type TimestampType = 'iso' | 'locale' | 'custom';
-interface TimestampTypes {
-    ISO: 'iso';
-    Locale: 'locale';
-    Custom: 'custom';
+/**
+ * Log levels ordered by severity.
+ * - trace: Very detailed debugging information
+ * - debug: Detailed information for debugging
+ * - info: General informational messages
+ * - warn: Warning conditions
+ * - error: Error conditions
+ * - fatal: Critical errors that may terminate the application
+ */
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/**
+ * A structured log entry passed to transports and formatters.
+ */
+interface LogEntry {
+    /** The log level of this entry */
+    level: LogLevel;
+    /** ISO 8601 formatted timestamp */
+    timestamp: string;
+    /** Original arguments passed to the log method */
+    args: unknown[];
+    /** Optional prefix from the logger hierarchy */
+    prefix?: string;
+    /** Context metadata attached to the logger */
+    context: Record<string, unknown>;
 }
-interface DiscordOptions {
-    enable: boolean;
-    webhookURL: string;
-    batchSize?: number;
-    batchDelay?: number;
-    maxRetries?: number;
-    retryDelayBase?: number;
-    formatEmbed?: (level: LogLevel, timestamp: string, message: string) => Record<string, unknown>;
+/**
+ * Pluggable transport interface.
+ * Implement this interface to create custom log transports.
+ */
+interface Transport {
+    /**
+     * Called for each log entry.
+     * @param entry - The structured log entry
+     */
+    log(entry: LogEntry): void | Promise<void>;
+    /**
+     * Optional cleanup method called when the logger is destroyed.
+     */
+    destroy?(): void | Promise<void>;
+}
+/**
+ * Timestamp option: preset string or custom formatter function.
+ * - 'iso': ISO 8601 format (default)
+ * - 'locale': Localized date/time string
+ * - function: Custom formatter
+ */
+type TimestampOption = 'iso' | 'locale' | ((date: Date) => string);
+/**
+ * Custom formatter function for log output.
+ * @param entry - The structured log entry
+ * @returns The formatted string to output to console
+ */
+type Formatter = (entry: LogEntry) => string;
+/**
+ * Options for creating a child logger.
+ */
+interface ChildLoggerOptions {
+    /** Prefix to prepend to log messages */
+    prefix?: string;
+    /** Additional context metadata */
+    context?: Record<string, unknown>;
+    /** Override log level for this child logger */
+    level?: LogLevel;
+    /** Override silent mode for this child logger */
+    silent?: boolean;
 }
+/**
+ * Main logger configuration options.
+ */
 interface LoggerOptions {
+    /** Minimum log level to output (default: 'debug') */
     level?: LogLevel;
+    /** Suppress all console output (default: false) */
+    silent?: boolean;
+    /** Enable colored output (default: true) */
     enableColors?: boolean;
-    discord?: DiscordOptions;
-    formatTimestamp?: (types: TimestampTypes, date?: Date) => [TimestampType, string];
-    formatLog?: (level: string, timestamp: string, args: unknown[]) => string;
+    /** Timestamp format (default: 'iso') */
+    timestamp?: TimestampOption;
+    /** Custom formatter for log output */
+    formatter?: Formatter;
+    /** Output logs as JSON (default: false) */
+    json?: boolean;
+    /** Initial transports to attach */
+    transports?: Transport[];
+    /** Prefix for all log messages */
+    prefix?: string;
+    /** Initial context metadata */
+    context?: Record<string, unknown>;
 }
 
 /**
- * A simple logger with colored outputs and timestamps.
+ * A lightweight, pluggable logger with colored outputs, structured logging, and transport support.
+ *
+ * @example
+ * ```typescript
+ * import { Logger } from '@feizk/logger';
+ *
+ * const logger = new Logger();
+ *
+ * logger.info('Hello, world!');
+ * logger.warn('This is a warning');
+ * logger.error('This is an error');
+ * ```
  */
 declare class Logger {
-    private options;
-    private level;
-    private discordQueue;
-    private isProcessing;
-    private processTimeout?;
+    private readonly options;
+    private readonly transports;
+    private readonly prefix?;
+    private readonly context;
+    /**
+     * Create a new Logger instance.
+     * @param options - Configuration options
+     */
     constructor(options?: LoggerOptions);
     /**
-     * Sets the minimum log level for filtering messages.
-     * @param level - The log level to set.
+     * Log a trace message (most verbose).
+     * @param args - Arguments to log
+     */
+    trace(...args: unknown[]): void;
+    /**
+     * Log a debug message.
+     * @param args - Arguments to log
+     */
+    debug(...args: unknown[]): void;
+    /**
+     * Log an info message.
+     * @param args - Arguments to log
+     */
+    info(...args: unknown[]): void;
+    /**
+     * Log a warning message.
+     * @param args - Arguments to log
+     */
+    warn(...args: unknown[]): void;
+    /**
+     * Log an error message.
+     * @param args - Arguments to log
+     */
+    error(...args: unknown[]): void;
+    /**
+     * Log a fatal message (most severe).
+     * @param args - Arguments to log
+     */
+    fatal(...args: unknown[]): void;
+    /**
+     * Set the minimum log level.
+     * @param level - The log level to set
      */
     setLevel(level: LogLevel): void;
     /**
-     * Sends a log message to Discord via webhook if configured.
-     * @param level - The log level.
-     * @param timestamp - The formatted timestamp.
-     * @param args - The log arguments.
+     * Get the current log level.
+     * @returns The current log level
      */
-    private sendToDiscord;
+    getLevel(): LogLevel;
     /**
-     * Processes the Discord queue by sending batches of embeds.
+     * Add a transport to the logger.
+     * @param transport - The transport to add
      */
-    private processQueue;
+    addTransport(transport: Transport): void;
     /**
-     * Sends a batch of embeds to Discord.
-     * @param embeds - The embeds to send.
+     * Remove a transport from the logger.
+     * @param transport - The transport to remove
      */
-    private sendBatch;
+    removeTransport(transport: Transport): void;
     /**
-     * Checks if a log level should be output based on the current log level.
-     * @param level - The log level to check.
-     * @returns True if the message should be logged.
+     * Create a child logger with additional prefix and context.
+     * @param options - Child logger options
+     * @returns A new Logger instance
      */
-    private shouldLog;
+    child(options?: ChildLoggerOptions): Logger;
     /**
-     * Logs an info message.
-     * @param args - The arguments to log.
+     * Destroy the logger and all its transports.
+     * Calls destroy() on all registered transports.
      */
-    info(...args: unknown[]): void;
+    destroy(): Promise<void>;
     /**
-     * Logs a warning message.
-     * @param args - The arguments to log.
+     * Core logging method - all public methods delegate here.
+     * @param level - The log level
+     * @param args - The arguments to log
      */
-    warn(...args: unknown[]): void;
+    private log;
     /**
-     * Logs an error message.
-     * @param args - The arguments to log.
+     * Write a log entry to the console.
+     * @param level - The log level
+     * @param entry - The log entry
      */
-    error(...args: unknown[]): void;
+    private writeToConsole;
     /**
-     * Logs a debug message.
-     * @param args - The arguments to log.
+     * Dispatch a log entry to a transport.
+     * @param transport - The transport
+     * @param entry - The log entry
      */
-    debug(...args: unknown[]): void;
+    private dispatchToTransport;
+    /**
+     * Check if a log level should be output.
+     * @param level - The log level to check
+     * @returns True if the message should be logged
+     */
+    private shouldLog;
 }
 
-declare const TIMESTAMP_TYPES: TimestampTypes;
+/**
+ * Log level priorities ordered by severity (lower = less severe).
+ */
+declare const LOG_LEVEL_PRIORITIES: Record<LogLevel, number>;
+/**
+ * Text labels for log levels.
+ */
+declare const LEVEL_LABELS: Record<LogLevel, string>;
+
+/**
+ * Get the colored label for a log level.
+ * Results are cached for performance.
+ * @param level - The log level
+ * @param enableColors - Whether to apply colors
+ * @returns The label string (colored if enabled)
+ */
+declare function getColoredLabel(level: LogLevel, enableColors: boolean): string;
+/**
+ * Format a timestamp based on the provided option.
+ * @param option - Preset string or custom formatter
+ * @param date - Date to format (default: current date)
+ * @returns Formatted timestamp string
+ */
+declare function formatTimestamp(option: TimestampOption, date?: Date): string;
+/**
+ * Format a log entry as JSON for structured logging.
+ * @param entry - The log entry to format
+ * @returns JSON string representation
+ */
+declare function formatJson(entry: LogEntry): string;
+/**
+ * Build the message string from log arguments.
+ * @param args - The log arguments
+ * @returns Formatted message string
+ */
+declare function buildMessage(args: unknown[]): string;
 
-export { type DiscordOptions, type LogLevel, Logger, type LoggerOptions, TIMESTAMP_TYPES, type TimestampType, type TimestampTypes };
+export { type ChildLoggerOptions, type Formatter, LEVEL_LABELS, LOG_LEVEL_PRIORITIES, type LogEntry, type LogLevel, Logger, type LoggerOptions, type TimestampOption, type Transport, buildMessage, formatJson, formatTimestamp, getColoredLabel };