@feizk/logger 1.6.0 → 2.0.0

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,85 +26,156 @@ 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
+## 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
+
+### Logger Methods
 
-Customize the logger with constructor options:
+- `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
+
+### Log Levels
+
+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({
-  enableColors: true, // Default: true
-  formatTimestamp: undefined, // Custom timestamp formatter function, Default: ISO format
-  formatLog: undefined, // Custom log formatter function, Default: undefined
-  level: 'debug', // 'debug' | 'info' | 'warn' | 'error', Default: 'debug'
-  discord: {
-    enable: false, // Enable Discord transport
-    webhookURL: '', // Discord webhook URL
-    formatEmbed: undefined, // Custom embed formatter function
-  },
+  timestamp: 'locale', // or 'iso' (default)
+});
+
+// Custom format
+const logger = new Logger({
+  timestamp: (date) => date.toISOString(),
 });
 ```
 
-#### Examples
+### Custom Formatter
 
 ```typescript
-// Disable colors
-const noColorLogger = new Logger({ enableColors: false });
-
-// Use locale timestamp
-const localeLogger = new Logger({
-  formatTimestamp: (types) => [types.Locale, new Date().toLocaleString()],
+const logger = new Logger({
+  formatter: (entry) =>
+    `[${entry.timestamp}] [${entry.level.toUpperCase()}] ${entry.args.join(' ')}`,
 });
+```
 
-// Custom timestamp
-const customLogger = new Logger({
-  formatTimestamp: () => [TIMESTAMP_TYPES.Custom, 'custom-time'],
-});
+### JSON Structured Logging
 
-// Filter logs below info level
-const infoLogger = new Logger({ level: 'info' });
-infoLogger.debug('Not logged');
-infoLogger.info('Logged'); // and higher
+```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"}}
+```
 
-// Change level dynamically
-logger.setLevel('error');
+### Child Logger
 
-// Enable Discord transport
-const discordLogger = new Logger({
-  discord: {
-    enable: true,
-    webhookURL: 'https://discord.com/api/webhooks/123456789/abcdef',
-  },
+```typescript
+const parent = new Logger({ prefix: 'app', context: { version: '1.0.0' } });
+
+const child = parent.child({
+  prefix: 'api',
+  context: { endpoint: '/users' },
 });
-discordLogger.error('This will be sent to Discord');
-
-// Custom embed formatting
-const customDiscordLogger = new Logger({
-  discord: {
-    enable: true,
-    webhookURL: 'https://discord.com/api/webhooks/123456789/abcdef',
-    formatEmbed: (level, timestamp, message) => ({
-      title: `${level} - Custom`,
-      description: `**Timestamp:** ${timestamp}\n**Message:** ${message}`,
-      color: 0xff0000, // Red
-    }),
-  },
+
+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: '...' }));
 ```
 
-## API
+### Removed Options
 
-### Logger
+- `discord` - Use `@feizk/logger-discord` instead
+- `formatTimestamp` - Use `timestamp` instead
+- `formatLog` - Use `formatter` instead
 
-- `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.
+## License
 
-All messages include a timestamp and are colored accordingly (unless disabled via options).
+MIT

package/dist/index.d.mts

@@ -1,70 +1,211 @@
-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;
-    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 {
-    enableColors?: boolean;
-    formatTimestamp?: (types: TimestampTypes, date?: Date) => [TimestampType, string];
-    formatLog?: (level: string, timestamp: string, args: unknown[]) => string;
+    /** Minimum log level to output (default: 'debug') */
     level?: LogLevel;
-    discord?: DiscordOptions;
+    /** Suppress all console output (default: false) */
+    silent?: boolean;
+    /** Enable colored output (default: true) */
+    enableColors?: boolean;
+    /** 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;
-    constructor(options?: LoggerOptions);
+    private readonly options;
+    private readonly transports;
+    private readonly prefix?;
+    private readonly context;
     /**
-     * Sets the minimum log level for filtering messages.
-     * @param level - The log level to set.
+     * Create a new Logger instance.
+     * @param options - Configuration options
      */
-    setLevel(level: LogLevel): void;
+    constructor(options?: LoggerOptions);
     /**
-     * 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.
+     * Log a trace message (most verbose).
+     * @param args - Arguments to log
      */
-    private sendToDiscord;
+    trace(...args: unknown[]): 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.
+     * Log a debug message.
+     * @param args - Arguments to log
      */
-    private shouldLog;
+    debug(...args: unknown[]): void;
     /**
-     * Logs an info message.
-     * @param args - The arguments to log.
+     * Log an info message.
+     * @param args - Arguments to log
      */
     info(...args: unknown[]): void;
     /**
-     * Logs a warning message.
-     * @param args - The arguments to log.
+     * Log a warning message.
+     * @param args - Arguments to log
      */
     warn(...args: unknown[]): void;
     /**
-     * Logs an error message.
-     * @param args - The arguments to log.
+     * Log an error message.
+     * @param args - Arguments to log
      */
     error(...args: unknown[]): void;
     /**
-     * Logs a debug message.
-     * @param args - The arguments to log.
+     * Log a fatal message (most severe).
+     * @param args - Arguments to log
      */
-    debug(...args: unknown[]): void;
+    fatal(...args: unknown[]): void;
+    /**
+     * Set the minimum log level.
+     * @param level - The log level to set
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Get the current log level.
+     * @returns The current log level
+     */
+    getLevel(): LogLevel;
+    /**
+     * Add a transport to the logger.
+     * @param transport - The transport to add
+     */
+    addTransport(transport: Transport): void;
+    /**
+     * Remove a transport from the logger.
+     * @param transport - The transport to remove
+     */
+    removeTransport(transport: Transport): void;
+    /**
+     * Create a child logger with additional prefix and context.
+     * @param options - Child logger options
+     * @returns A new Logger instance
+     */
+    child(options?: ChildLoggerOptions): Logger;
+    /**
+     * Destroy the logger and all its transports.
+     * Calls destroy() on all registered transports.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Core logging method - all public methods delegate here.
+     * @param level - The log level
+     * @param args - The arguments to log
+     */
+    private log;
+    /**
+     * Write a log entry to the console.
+     * @param level - The log level
+     * @param entry - The log entry
+     */
+    private writeToConsole;
+    /**
+     * Dispatch a log entry to a transport.
+     * @param transport - The transport
+     * @param entry - The log entry
+     */
+    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>;
 
-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 };