@rawnodes/logger 1.6.0 → 1.8.0

package/README.md

@@ -1,16 +1,16 @@
 # @rawnodes/logger
 
-Flexible Winston-based logger with AsyncLocalStorage context, level overrides, and timing utilities.
+Flexible Winston-based logger with AsyncLocalStorage context, level rules, and multiple output formats.
 
 ## Features
 
+- **Multiple Formats** - JSON, plain (colored), logfmt, simple
 - **Context Propagation** - Automatic context via AsyncLocalStorage
-- **Level Overrides** - Debug specific users/modules without global log level change
+- **Level Rules** - Configure log levels per module/context in config
 - **Lazy Meta** - Defer metadata creation until log level check passes
 - **Timing Utilities** - Built-in performance measurement
 - **Request ID** - Generate and extract request IDs
-- **Secret Masking** - Mask sensitive data in logs
-- **Singleton Factory** - Easy setup with `createSingletonLogger()`
+- **Secret Masking** - Automatic masking of sensitive data
 - **TypeScript First** - Full generic type support
 
 ## Installation
@@ -23,241 +23,519 @@ npm install @rawnodes/logger
 
 ## Quick Start
 
-### 1. Create your app logger
-
 ```typescript
-// src/logger/app.logger.ts
-import { createSingletonLogger, type LoggerContext } from '@rawnodes/logger';
+import { Logger } from '@rawnodes/logger';
 
-export interface AppLoggerContext extends LoggerContext {
-  userId?: number;
-  requestId?: string;
-}
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+});
 
-export const AppLogger = createSingletonLogger<AppLoggerContext>();
+logger.info('Hello world');
+logger.info('User logged in', { userId: 123 });
 ```
 
-### 2. Initialize on startup
+## Configuration
+
+### Basic Config
 
 ```typescript
-// src/main.ts
-import { AppLogger } from './logger/app.logger.js';
+import { Logger } from '@rawnodes/logger';
 
-AppLogger.getInstance({
-  level: 'info',
-  console: { level: 'debug' },
-  file: {
+const logger = Logger.create({
+  level: 'info',                    // default log level
+  console: { format: 'plain' },     // console output format
+  file: {                           // optional file output
+    format: 'json',
     dirname: 'logs',
     filename: 'app-%DATE%.log',
-    level: 'info',
     datePattern: 'YYYY-MM-DD',
     maxFiles: '14d',
+    maxSize: '20m',
   },
 });
 ```
 
-### 3. Use in your code
+### Level Rules
+
+Configure different log levels for specific modules or contexts:
 
 ```typescript
-import { AppLogger } from './logger/app.logger.js';
+const logger = Logger.create({
+  level: {
+    default: 'info',
+    rules: [
+      { match: { context: 'auth' }, level: 'debug' },        // debug for auth module
+      { match: { context: 'database' }, level: 'warn' },     // warn for database
+      { match: { userId: 123 }, level: 'debug' },            // debug for user 123
+      { match: { context: 'api', userId: 456 }, level: 'silly' }, // combined match
+    ],
+  },
+  console: { format: 'plain' },
+});
 
-const logger = AppLogger.for('UserService');
+const authLogger = logger.for('auth');
+authLogger.debug('This will be logged');  // matches rule
 
-logger.info('User created', { userId: 123 });
-logger.error('Failed to create user', { error });
+const dbLogger = logger.for('database');
+dbLogger.info('This will NOT be logged'); // level is warn
 ```
 
-### 4. Add context in middleware
+Rules from config are **readonly** and cannot be removed via API.
+
+### Output Formats
+
+| Format | Description | Example |
+|--------|-------------|---------|
+| `json` | Structured JSON | `{"level":"info","message":"hello","timestamp":"..."}` |
+| `plain` | Colored, human-readable | `[2025-01-01T12:00:00] info [APP] hello` |
+| `logfmt` | Key=value pairs | `level=info msg=hello context=APP ts=2025-01-01T12:00:00` |
+| `simple` | Minimal | `[2025-01-01T12:00:00] info: hello` |
 
 ```typescript
-// Express middleware
-app.use((req, res, next) => {
-  const context: AppLoggerContext = {
-    userId: req.user?.id,
-    requestId: req.headers['x-request-id'] || generateRequestId(),
-  };
-  AppLogger.getStore().run(context, () => next());
+// Different formats for console and file
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },   // colored for development
+  file: {
+    format: 'json',               // structured for log aggregation
+    dirname: 'logs',
+    filename: 'app-%DATE%.log',
+  },
 });
 ```
 
-## Configuration
+### Per-Transport Level
+
+Each transport can have its own log level:
 
 ```typescript
-interface LoggerConfig {
-  level: string; // Default log level
+const logger = Logger.create({
+  level: 'silly',                        // accept all at logger level
+  console: {
+    format: 'plain',
+    level: 'debug',                      // console: debug and above
+  },
+  file: {
+    format: 'json',
+    level: 'warn',                       // file: only warn and error
+    dirname: 'logs',
+    filename: 'app-%DATE%.log',
+  },
+});
+```
+
+| Scenario | Console | File |
+|----------|---------|------|
+| Development | `debug` | — |
+| Production | `info` | `warn` |
+| Troubleshooting | `debug` | `info` |
+| Critical alerts | `info` | `error` |
+
+This is useful for sending only critical errors to alerting systems while keeping verbose logs in console.
+
+### Per-Transport Rules
 
+Each transport can have its own filtering rules. Use `level: 'off'` with rules to create a whitelist pattern:
+
+```typescript
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+  file: {
+    format: 'json',
+    level: 'off',                              // off by default
+    rules: [
+      { match: { context: 'payments' }, level: 'error' },  // only errors from payments
+      { match: { context: 'auth' }, level: 'warn' },       // warn+ from auth
+    ],
+    dirname: 'logs',
+    filename: 'critical-%DATE%.log',
+  },
+});
+
+// Only error logs from 'payments' context go to file
+logger.for('payments').error('Payment failed');  // → file
+logger.for('payments').info('Processing');       // ✗ not logged to file
+logger.for('other').error('Generic error');      // ✗ not logged to file (no matching rule)
+```
+
+Rules can also match store context (AsyncLocalStorage):
+
+```typescript
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+  file: {
+    format: 'json',
+    level: 'off',
+    rules: [
+      { match: { userId: 123 }, level: 'debug' },           // debug for specific user
+      { match: { context: 'api', premium: true }, level: 'debug' }, // debug for premium API users
+    ],
+    dirname: 'logs',
+    filename: 'debug-%DATE%.log',
+  },
+});
+
+// Logs for user 123 go to file
+store.run({ userId: 123 }, () => {
+  logger.debug('User action');  // → file
+});
+```
+
+Use `level: 'off'` in rules to suppress specific contexts:
+
+```typescript
+const logger = Logger.create({
+  level: 'debug',
   console: {
-    level: string; // Console transport level
-  };
+    format: 'plain',
+    level: 'debug',
+    rules: [
+      { match: { context: 'noisy-module' }, level: 'off' },  // suppress noisy logs
+    ],
+  },
+});
 
-  file?: {
-    dirname: string;      // Log directory
-    filename: string;     // Filename pattern (supports %DATE%)
-    level: string;        // File transport level
-    datePattern: string;  // Date pattern for rotation
-    zippedArchive?: boolean;
-    maxSize?: string;     // e.g., '20m'
-    maxFiles?: string;    // e.g., '14d'
-  };
+logger.for('noisy-module').debug('Spam');  // ✗ not logged
+logger.for('other').debug('Useful info');  // → logged
+```
+
+## External Transports
+
+### Discord
+
+Send logs to Discord via webhooks with rich embeds:
+
+```typescript
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+  discord: {
+    webhookUrl: 'https://discord.com/api/webhooks/xxx/yyy',
+    level: 'error',                    // only errors to Discord
+    username: 'My App Logger',         // optional bot name
+    avatarUrl: 'https://...',          // optional avatar
+    embedColors: {                     // optional custom colors
+      error: 0xFF0000,
+      warn: 0xFFAA00,
+    },
+    batchSize: 10,                     // messages per batch (default: 10)
+    flushInterval: 2000,               // flush interval ms (default: 2000)
+  },
+});
+```
+
+### Telegram
+
+Send logs to Telegram chats/channels:
+
+```typescript
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+  telegram: {
+    botToken: process.env.TG_BOT_TOKEN!,
+    chatId: process.env.TG_CHAT_ID!,
+    level: 'warn',                     // warn and above
+    parseMode: 'Markdown',             // 'Markdown' | 'MarkdownV2' | 'HTML'
+    disableNotification: false,        // mute non-error by default
+    threadId: 123,                     // optional forum topic ID
+    replyToMessageId: 456,             // optional reply to message
+    batchSize: 20,                     // default: 20
+    flushInterval: 1000,               // default: 1000
+  },
+});
+```
+
+Use `level: 'off'` with rules for selective logging:
+
+```typescript
+telegram: {
+  botToken: '...',
+  chatId: '...',
+  level: 'off',                        // off by default
+  rules: [
+    { match: { context: 'payments' }, level: 'error' },  // only payment errors
+  ],
 }
 ```
 
-## Level Overrides
+### CloudWatch
 
-Debug specific users/modules without changing global log level:
+Send logs to AWS CloudWatch Logs:
 
 ```typescript
-// Enable debug logging for user 123
-logger.setLevelOverride({ userId: 123 }, 'debug');
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+  cloudwatch: {
+    logGroupName: '/app/my-service',
+    logStreamName: `${hostname}-${Date.now()}`,
+    region: 'us-east-1',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    createLogGroup: true,              // auto-create group (default: false)
+    createLogStream: true,             // auto-create stream (default: true)
+    batchSize: 100,                    // default: 100
+    flushInterval: 1000,               // default: 1000
+  },
+});
+```
+
+### Transport Options
+
+All external transports support:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `level` | — | Log level filter |
+| `rules` | — | Per-transport filtering rules |
+| `batchSize` | varies | Max messages per batch |
+| `flushInterval` | varies | Flush interval in ms |
+| `maxRetries` | 3 | Retry count on failure |
+| `retryDelay` | 1000 | Base retry delay in ms |
+
+## Singleton Pattern
+
+For app-wide logging:
+
+```typescript
+// src/logger.ts
+import { createSingletonLogger, type LoggerContext } from '@rawnodes/logger';
+
+export interface AppContext extends LoggerContext {
+  userId?: number;
+  requestId?: string;
+}
+
+export const AppLogger = createSingletonLogger<AppContext>();
+
+// src/main.ts
+import { AppLogger } from './logger.js';
+
+AppLogger.init({
+  level: {
+    default: 'info',
+    rules: [{ match: { context: 'debug-module' }, level: 'debug' }],
+  },
+  console: { format: 'plain' },
+});
+
+// Anywhere in your app
+const logger = AppLogger.for('UserService');
+logger.info('User created', { userId: 123 });
+```
+
+## Context Propagation
+
+Automatically include context in all logs within an async scope:
+
+```typescript
+// Express middleware
+app.use((req, res, next) => {
+  const context = {
+    userId: req.user?.id,
+    requestId: req.headers['x-request-id'] || generateRequestId(),
+  };
+  AppLogger.getStore().run(context, () => next());
+});
+
+// All logs within this request will include userId and requestId
+logger.info('Processing request');
+// Output: [2025-01-01T12:00:00] info [APP] Processing request
+//   userId: 123
+//   requestId: abc-123
+```
 
-// Enable debug only for 'auth' module
-const authLogger = logger.child('auth');
-logger.setLevelOverride({ context: 'auth' }, 'debug');
+## Dynamic Level Overrides
 
-// Enable debug for specific user in specific module
-logger.setLevelOverride({ context: 'auth', userId: 123 }, 'debug');
+Add/remove level overrides at runtime:
+
+```typescript
+// Enable debug for specific user (e.g., for troubleshooting)
+logger.setLevelOverride({ userId: 123 }, 'debug');
 
-// Now only auth module logs for user 123 will include debug level
-// Other users and modules still get the default level
+// Enable debug for specific module
+logger.setLevelOverride({ context: 'payments' }, 'debug');
 
-// Remove override when done
-logger.removeLevelOverride({ context: 'auth', userId: 123 });
+// Remove override
+logger.removeLevelOverride({ userId: 123 });
 
-// Or clear all overrides
+// Clear all dynamic overrides (keeps config rules)
 logger.clearLevelOverrides();
+
+// Get all overrides
+const overrides = logger.getLevelOverrides();
+// [{ match: { context: 'payments' }, level: 'debug', readonly: false }]
 ```
 
 ## Lazy Meta
 
-Avoid creating objects when log level doesn't allow logging:
+Defer expensive object creation:
 
 ```typescript
-// Object is always created (even if debug is disabled)
-logger.debug('message', { heavy: computeExpensiveData() });
+// BAD: Object created even if debug is disabled
+logger.debug('Data processed', { result: expensiveSerialize(data) });
 
-// Function is only called when debug level is enabled
-logger.debug('message', () => ({ heavy: computeExpensiveData() }));
+// GOOD: Function only called when debug is enabled
+logger.debug('Data processed', () => ({ result: expensiveSerialize(data) }));
 ```
 
-This is useful for performance-critical code where you want debug logs but don't want to pay the cost of creating log metadata when debug is disabled.
-
-## Timing
+## Child Loggers
 
-Measure execution time:
+Create scoped loggers:
 
 ```typescript
-const logger = AppLogger.getInstance();
+const logger = AppLogger.for('PaymentService');
+logger.info('Processing payment');
+// Output: [timestamp] info [PaymentService] Processing payment
+
+const stripeLogger = logger.for('Stripe');
+stripeLogger.info('Charging card');
+// Output: [timestamp] info [Stripe] Charging card
+```
+
+## Utilities
+
+### Timing
 
-// Manual timing
-const timer = logger.time('database-query');
-await db.query('SELECT ...');
-logger.timeEnd(timer); // Logs: "database-query completed in 45.23ms"
+```typescript
+import { measureAsync, measureSync } from '@rawnodes/logger';
 
-// Async wrapper
-const users = await logger.timeAsync('fetch-users', async () => {
+// Async
+const { result, timing } = await measureAsync('fetch-users', async () => {
   return await userService.findAll();
 });
+console.log(timing); // { label: 'fetch-users', durationMs: 45.23, durationFormatted: '45.23ms' }
+
+// Sync
+const { result, timing } = measureSync('compute', () => {
+  return heavyComputation();
+});
 ```
 
-## Request ID Utilities
+### Request ID
 
 ```typescript
-import { generateRequestId, getOrGenerateRequestId } from '@rawnodes/logger';
+import { generateRequestId, extractRequestId, getOrGenerateRequestId } from '@rawnodes/logger';
 
-// Generate new request ID
-const requestId = generateRequestId();
-// => "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+// Generate new
+generateRequestId();                          // "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+generateRequestId({ short: true });           // "a1b2c3d4"
+generateRequestId({ prefix: 'req' });         // "req-a1b2c3d4-e5f6-..."
 
-// Short format
-const shortId = generateRequestId({ short: true });
-// => "a1b2c3d4"
+// Extract from headers (checks x-request-id, x-correlation-id, x-trace-id)
+extractRequestId(req.headers);                // string | undefined
 
-// With prefix
-const prefixedId = generateRequestId({ prefix: 'req' });
-// => "req-a1b2c3d4-e5f6-..."
-
-// Extract from headers or generate new
-const id = getOrGenerateRequestId(req.headers);
+// Extract or generate
+getOrGenerateRequestId(req.headers);          // always returns string
 ```
 
-## Secret Masking
+### Secret Masking
+
+Automatically masks sensitive fields in logs:
 
 ```typescript
-import { maskSecrets } from '@rawnodes/logger';
+import { maskSecrets, createMasker } from '@rawnodes/logger';
 
-const masked = maskSecrets({
+maskSecrets({
   user: 'admin',
   password: 'secret123',
-  apiToken: 'tok_abc123xyz',
-  url: 'postgres://user:pass@localhost/db',
+  apiKey: 'key_abc123',
 });
+// { user: 'admin', password: '***', apiKey: '***' }
 
-// Result:
-// {
-//   user: 'admin',
-//   password: '***',
-//   apiToken: '***',
-//   url: 'postgres://user:***@localhost/db'
-// }
+// Custom masker
+const masker = createMasker({
+  patterns: ['ssn', 'creditCard'],
+  mask: '[REDACTED]'
+});
 ```
 
-## Child Loggers
+**Default masked patterns:** `password`, `secret`, `token`, `apikey`, `api_key`, `api-key`, `auth`, `credential`, `private`
+
+## Logfmt Utilities
 
-Create scoped loggers with automatic context:
+Helper functions for logfmt format:
 
 ```typescript
-// Get child logger with context name
-const logger = AppLogger.for('PaymentService');
-logger.info('Processing payment'); // [PaymentService] Processing payment
+import { flattenObject, formatLogfmt, formatLogfmtValue } from '@rawnodes/logger';
+
+flattenObject({ user: { id: 123, name: 'John' } });
+// { 'user.id': 123, 'user.name': 'John' }
 
-// Or from instance
-const baseLogger = AppLogger.getInstance();
-const childLogger = baseLogger.getChildLogger('EmailService');
+formatLogfmt({ level: 'info', msg: 'hello', userId: 123 });
+// "level=info msg=hello userId=123"
 ```
 
 ## API Reference
 
-### `createSingletonLogger<TContext>()`
-
-Creates a singleton logger factory.
+### Logger
 
-Returns:
 ```typescript
-interface SingletonLogger<TContext> {
-  getInstance(config?: LoggerConfig): BaseLogger<TContext>;
-  getStore(): LoggerStore<TContext>;
+class Logger<TContext> {
+  static create(config: LoggerConfig, store?: LoggerStore): Logger;
+
   for(context: string): Logger;
-  setLevelOverride(match: Partial<TContext>, level: string): void;
-  removeLevelOverride(match: Partial<TContext>): void;
-  getLevelOverrides(): LevelOverride<TContext>[];
+  getStore(): LoggerStore<TContext>;
+
+  // Logging
+  error(message: string, error?: Error, meta?: Meta): void;
+  warn(message: string, meta?: Meta): void;
+  info(message: string, meta?: Meta): void;
+  http(message: string, meta?: Meta): void;
+  verbose(message: string, meta?: Meta): void;
+  debug(message: string, meta?: Meta): void;
+  silly(message: string, meta?: Meta): void;
+
+  // Level overrides
+  setLevelOverride(match: LevelOverrideMatch, level: LogLevel): void;
+  removeLevelOverride(match: LevelOverrideMatch): boolean;
   clearLevelOverrides(): void;
+  getLevelOverrides(): LevelOverride[];
+
+  // Winston profiling
+  profile(id: string, meta?: object): void;
 }
 ```
 
-### `BaseLogger<TContext>`
-
-Main logger class with methods:
-- `log(message, context?, meta?)`
-- `info(message, context?, meta?)`
-- `warn(message, context?, meta?)`
-- `error(message, error?, context?)`
-- `debug(message, context?, meta?)`
-- `verbose(message, context?, meta?)`
-- `time(label): Timer`
-- `timeEnd(timer, context?): TimingResult`
-- `timeAsync<T>(label, fn, context?): Promise<T>`
-- `getChildLogger(context): Logger`
-- `getStore(): LoggerStore<TContext>`
-- `setLevelOverride(match, level)`
-- `removeLevelOverride(match)`
-- `getLevelOverrides()`
-- `clearLevelOverrides()`
-
-### `LoggerStore<TContext>`
-
-AsyncLocalStorage wrapper:
-- `getStore(): TContext | undefined`
-- `run<T>(context, fn): T`
+### Types
+
+```typescript
+type LogLevel = 'error' | 'warn' | 'info' | 'http' | 'verbose' | 'debug' | 'silly' | 'off';
+type LogFormat = 'json' | 'plain' | 'logfmt' | 'simple';
+type Meta = object | (() => object);
+
+interface LoggerConfig {
+  level: LogLevel | {
+    default: LogLevel;
+    rules?: LevelRule[];
+  };
+  console: {
+    format: LogFormat;
+    level?: LogLevel;      // optional, overrides global level
+    rules?: LevelRule[];   // optional, per-transport filtering
+  };
+  file?: {
+    format: LogFormat;
+    level?: LogLevel;      // optional, overrides global level
+    rules?: LevelRule[];   // optional, per-transport filtering
+    dirname: string;
+    filename: string;
+    datePattern?: string;
+    maxFiles?: string;
+    maxSize?: string;
+    zippedArchive?: boolean;
+  };
+}
+
+interface LevelRule {
+  match: Record<string, unknown> & { context?: string };
+  level: LogLevel;
+}
+```
 
 ## Integration Examples
 
@@ -295,7 +573,7 @@ export class LoggerMiddleware implements NestMiddleware {
 }
 ```
 
-### Telegraf (Telegram Bot)
+### Telegraf
 
 ```typescript
 import { Telegraf } from 'telegraf';