@feizk/logger 1.7.0 → 2.0.1

package/README.md

@@ -1,6 +1,17 @@
 # @feizk/logger
 
-A simple logger package with colored outputs and timestamps.
+A lightweight, pluggable logger with colored outputs, structured logging, and transport support.
+
+## Features
+
+- 🚀 **Zero dependencies** - No external runtime dependencies
+- 🎨 **Colored output** - ANSI color codes for terminal output
+- 📊 **6 log levels** - trace, debug, info, warn, error, fatal
+- 📝 **Structured logging** - JSON mode for production environments
+- 🔌 **Pluggable transports** - Add custom transports (files, databases, etc.)
+- 👶 **Child loggers** - Create prefixed loggers with merged context
+- ⏱️ **Custom timestamps** - Presets (iso, locale) or custom format
+- 🎯 **Type-safe** - Full TypeScript support
 
 ## Installation
 
@@ -15,45 +26,155 @@ import { Logger } from '@feizk/logger';
 
 const logger = new Logger();
 
-logger.info('This is an info message');
+logger.info('Hello, world!');
 logger.warn('This is a warning');
 logger.error('This is an error');
-logger.debug('This is a debug message');
+logger.debug('Debug information');
+logger.trace('Very detailed trace');
+logger.fatal('Critical error!');
 ```
 
 ## Options
 
-| Option          | Type                             | Default     | Description                           |
-| --------------- | -------------------------------- | ----------- | ------------------------------------- |
-| `enableColors`  | `boolean`                        | `true`      | Enable colored output                 |
-| `formatTimestamp`| `function \| undefined`          | `ISO format`| Custom timestamp formatter function   |
-| `formatLog`     | `function \| undefined`          | `undefined` | Custom log formatter function         |
-| `level`         | `'debug' \| 'info' \| 'warn' \| 'error'` | `'debug'` | Minimum log level                     |
-| `discord`       | `object \| undefined`            | `undefined` | Discord transport options             |
+| Option         | Type                                                           | Default     | Description                  |
+| -------------- | -------------------------------------------------------------- | ----------- | ---------------------------- |
+| `level`        | `'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'` | `'debug'`   | Minimum log level to output  |
+| `silent`       | `boolean`                                                      | `false`     | Suppress all console output  |
+| `enableColors` | `boolean`                                                      | `true`      | Enable colored output        |
+| `timestamp`    | `'iso' \| 'locale' \| (date: Date) => string`                  | `'iso'`     | Timestamp format             |
+| `json`         | `boolean`                                                      | `false`     | Output logs as JSON          |
+| `formatter`    | `(entry: LogEntry) => string`                                  | `undefined` | Custom log formatter         |
+| `transports`   | `Transport[]`                                                  | `[]`        | Initial transports to attach |
+| `prefix`       | `string`                                                       | `undefined` | Prefix for all log messages  |
+| `context`      | `Record<string, unknown>`                                      | `{}`        | Initial context metadata     |
+
+## API
 
-### Discord Options
+### Logger Methods
 
-The `discord` option configures Discord webhook integration. It has the following properties:
+- `trace(...args)` - Log a trace message (most verbose)
+- `debug(...args)` - Log a debug message
+- `info(...args)` - Log an info message
+- `warn(...args)` - Log a warning message
+- `error(...args)` - Log an error message
+- `fatal(...args)` - Log a fatal message (most severe)
+- `setLevel(level)` - Set the minimum log level
+- `getLevel()` - Get the current log level
+- `addTransport(transport)` - Add a custom transport
+- `removeTransport(transport)` - Remove a transport
+- `child(options)` - Create a child logger
+- `destroy()` - Destroy the logger and all transports
 
-- `enable`: `boolean`, default `false` - Enable Discord transport
-- `webhookURL`: `string`, default `''` - Discord webhook URL
-- `formatEmbed`: `function \| undefined`, default `undefined` - Custom embed formatter function
-- `batchSize`: `number`, default `10` - Number of embeds per batch request
-- `batchDelay`: `number`, default `2000` - Delay in ms between batch sends
-- `maxRetries`: `number`, default `3` - Maximum retry attempts for failed sends
-- `retryDelayBase`: `number`, default `1000` - Base delay in ms for exponential backoff
+### Log Levels
 
-## API
+Logs are filtered by severity. The order from least to most severe:
+
+1. `trace` - Very detailed debugging information
+2. `debug` - Detailed information for debugging
+3. `info` - General informational messages
+4. `warn` - Warning conditions
+5. `error` - Error conditions
+6. `fatal` - Critical errors
+
+## Advanced Usage
+
+### Custom Timestamp
+
+```typescript
+const logger = new Logger({
+  timestamp: 'locale', // or 'iso' (default)
+});
+
+// Custom format
+const logger = new Logger({
+  timestamp: (date) => date.toISOString(),
+});
+```
+
+### Custom Formatter
+
+```typescript
+const logger = new Logger({
+  formatter: (entry) =>
+    `[${entry.timestamp}] [${entry.level.toUpperCase()}] ${entry.args.join(' ')}`,
+});
+```
+
+### JSON Structured Logging
+
+```typescript
+const logger = new Logger({ json: true });
+logger.info('User logged in', { userId: '123' });
+// Output: {"level":"info","timestamp":"2024-01-01T00:00:00.000Z","message":"User logged in","context":{"userId":"123"}}
+```
+
+### Child Logger
+
+```typescript
+const parent = new Logger({ prefix: 'app', context: { version: '1.0.0' } });
 
-### Logger
+const child = parent.child({
+  prefix: 'api',
+  context: { endpoint: '/users' },
+});
+
+child.info('Request received');
+// Output includes prefix "app:api" and merged context
+```
+
+### Pluggable Transports
+
+```typescript
+import { Logger, type Transport, type LogEntry } from '@feizk/logger';
+
+// Create a custom transport
+class FileTransport implements Transport {
+  private stream: WriteStream;
+
+  constructor(path: string) {
+    this.stream = createWriteStream(path);
+  }
+
+  log(entry: LogEntry): void {
+    this.stream.write(JSON.stringify(entry) + '\n');
+  }
+
+  destroy(): void {
+    this.stream.end();
+  }
+}
+
+// Use the transport
+const logger = new Logger();
+logger.addTransport(new FileTransport('/var/log/app.log'));
+logger.info('This will be logged to the file');
+```
+
+## Migration from v1.x
+
+### Discord Transport
+
+Discord transport has been moved to a separate package. Use `@feizk/logger-discord` instead:
+
+```typescript
+// v1.x
+const logger = new Logger({
+  discord: { enable: true, webhookURL: '...' },
+});
+
+// v2.x
+import { Logger } from '@feizk/logger';
+import { DiscordTransport } from '@feizk/logger-discord';
+
+const logger = new Logger();
+logger.addTransport(new DiscordTransport({ webhookURL: '...' }));
+```
 
-- `info(...args: unknown[])`: Logs an info message.
-- `warn(...args: unknown[])`: Logs a warning message.
-- `error(...args: unknown[])`: Logs an error message.
-- `debug(...args: unknown[])`: Logs a debug message.
-- `setLevel(level: LogLevel)`: Sets the minimum log level for filtering messages.
+### Removed Options
 
-All messages include a timestamp and are colored accordingly (unless disabled via options).
+- `discord` - Use `@feizk/logger-discord` instead
+- `formatTimestamp` - Use `timestamp` instead
+- `formatLog` - Use `formatter` instead
 
 ## License
 

package/dist/index.d.mts

@@ -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 };