@rawnodes/logger 1.5.1 → 1.7.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,321 @@ 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
+
+const dbLogger = logger.for('database');
+dbLogger.info('This will NOT be logged'); // level is warn
+```
+
+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
+// 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',
+  },
+});
+```
+
+## 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 });
-logger.error('Failed to create user', { error });
 ```
 
-### 4. Add context in middleware
+## Context Propagation
+
+Automatically include context in all logs within an async scope:
 
 ```typescript
 // Express middleware
 app.use((req, res, next) => {
-  const context: AppLoggerContext = {
+  const context = {
     userId: req.user?.id,
     requestId: req.headers['x-request-id'] || generateRequestId(),
   };
   AppLogger.getStore().run(context, () => next());
 });
-```
 
-## Configuration
-
-```typescript
-interface LoggerConfig {
-  level: string; // Default log level
-
-  console: {
-    level: string; // Console transport level
-  };
-
-  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'
-  };
-}
+// 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
 ```
 
-## Level Overrides
+## Dynamic Level Overrides
 
-Debug specific users/modules without changing global log level:
+Add/remove level overrides at runtime:
 
 ```typescript
-// Enable debug logging for user 123
+// Enable debug for specific user (e.g., for troubleshooting)
 logger.setLevelOverride({ userId: 123 }, 'debug');
 
-// Enable debug only for 'auth' module
-const authLogger = logger.child('auth');
-logger.setLevelOverride({ context: 'auth' }, 'debug');
-
-// Enable debug for specific user in specific module
-logger.setLevelOverride({ context: 'auth', 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
+```
 
-// Manual timing
-const timer = logger.time('database-query');
-await db.query('SELECT ...');
-logger.timeEnd(timer); // Logs: "database-query completed in 45.23ms"
+## Utilities
 
-// Async wrapper
-const users = await logger.timeAsync('fetch-users', async () => {
+### Timing
+
+```typescript
+import { measureAsync, measureSync } from '@rawnodes/logger';
+
+// 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';
-
-// Generate new request ID
-const requestId = generateRequestId();
-// => "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+import { generateRequestId, extractRequestId, getOrGenerateRequestId } from '@rawnodes/logger';
 
-// Short format
-const shortId = generateRequestId({ short: true });
-// => "a1b2c3d4"
+// Generate new
+generateRequestId();                          // "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+generateRequestId({ short: true });           // "a1b2c3d4"
+generateRequestId({ prefix: 'req' });         // "req-a1b2c3d4-e5f6-..."
 
-// With prefix
-const prefixedId = generateRequestId({ prefix: 'req' });
-// => "req-a1b2c3d4-e5f6-..."
+// Extract from headers (checks x-request-id, x-correlation-id, x-trace-id)
+extractRequestId(req.headers);                // string | undefined
 
-// 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`
 
-Create scoped loggers with automatic context:
+## Logfmt Utilities
+
+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>()`
+### Logger
 
-Creates a singleton logger factory.
-
-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';
+type LogFormat = 'json' | 'plain' | 'logfmt' | 'simple';
+type Meta = object | (() => object);
+
+interface LoggerConfig {
+  level: LogLevel | {
+    default: LogLevel;
+    rules?: LevelRule[];
+  };
+  console: { format: LogFormat };
+  file?: {
+    format: LogFormat;
+    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 +375,7 @@ export class LoggerMiddleware implements NestMiddleware {
 }
 ```
 
-### Telegraf (Telegram Bot)
+### Telegraf
 
 ```typescript
 import { Telegraf } from 'telegraf';

package/dist/index.d.mts

@@ -10,7 +10,12 @@ declare const LOG_LEVELS: {
 type LogLevel = keyof typeof LOG_LEVELS;
 declare function isValidLogLevel(level: string): level is LogLevel;
 declare function assertLogLevel(level: string): asserts level is LogLevel;
+type LogFormat = 'json' | 'plain' | 'logfmt' | 'simple';
+interface ConsoleConfig {
+    format: LogFormat;
+}
 interface FileConfig {
+    format: LogFormat;
     dirname: string;
     filename: string;
     datePattern?: string;
@@ -18,8 +23,20 @@ interface FileConfig {
     maxSize?: string;
     maxFiles?: string;
 }
-interface LoggerConfig {
+interface LevelRule {
+    match: Record<string, unknown> & {
+        context?: string;
+    };
     level: LogLevel;
+}
+interface LevelConfigObject {
+    default: LogLevel;
+    rules?: LevelRule[];
+}
+type LevelConfig = LogLevel | LevelConfigObject;
+interface LoggerConfig {
+    level: LevelConfig;
+    console: ConsoleConfig;
     file?: FileConfig;
 }
 type LoggerContext = Record<string, unknown>;
@@ -29,6 +46,7 @@ type LevelOverrideMatch<TContext extends LoggerContext> = Partial<TContext> & {
 interface LevelOverride<TContext extends LoggerContext> {
     match: LevelOverrideMatch<TContext>;
     level: LogLevel;
+    readonly?: boolean;
 }
 type Meta = object | (() => object);
 
@@ -46,7 +64,7 @@ declare class Logger<TContext extends LoggerContext = LoggerContext> {
     for(context: string): Logger<TContext>;
     getStore(): LoggerStore<TContext>;
     setLevelOverride(match: LevelOverrideMatch<TContext>, level: LogLevel): void;
-    removeLevelOverride(match: LevelOverrideMatch<TContext>): void;
+    removeLevelOverride(match: LevelOverrideMatch<TContext>): boolean;
     clearLevelOverrides(): void;
     getLevelOverrides(): LevelOverride<TContext>[];
     profile(id: string, meta?: object): void;
@@ -102,4 +120,8 @@ interface MaskSecretsOptions {
 declare function maskSecrets(obj: unknown, options?: MaskSecretsOptions): unknown;
 declare function createMasker(options?: MaskSecretsOptions): (obj: unknown) => unknown;
 
-export { type FileConfig, LOG_LEVELS, type LevelOverride, type LevelOverrideMatch, type LogLevel, Logger, type LoggerConfig, type LoggerContext, LoggerStore, type MaskSecretsOptions, type Meta, type RequestIdOptions, type SingletonLogger, type TimingResult, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, generateRequestId, getOrGenerateRequestId, isValidLogLevel, maskSecrets, measureAsync, measureSync };
+declare function flattenObject(obj: Record<string, unknown>, prefix?: string): Record<string, unknown>;
+declare function formatLogfmtValue(value: unknown): string;
+declare function formatLogfmt(data: Record<string, unknown>): string;
+
+export { type ConsoleConfig, type FileConfig, LOG_LEVELS, type LevelConfig, type LevelConfigObject, type LevelOverride, type LevelOverrideMatch, type LevelRule, type LogFormat, type LogLevel, Logger, type LoggerConfig, type LoggerContext, LoggerStore, type MaskSecretsOptions, type Meta, type RequestIdOptions, type SingletonLogger, type TimingResult, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatLogfmt, formatLogfmtValue, generateRequestId, getOrGenerateRequestId, isValidLogLevel, maskSecrets, measureAsync, measureSync };

package/dist/index.d.ts

@@ -10,7 +10,12 @@ declare const LOG_LEVELS: {
 type LogLevel = keyof typeof LOG_LEVELS;
 declare function isValidLogLevel(level: string): level is LogLevel;
 declare function assertLogLevel(level: string): asserts level is LogLevel;
+type LogFormat = 'json' | 'plain' | 'logfmt' | 'simple';
+interface ConsoleConfig {
+    format: LogFormat;
+}
 interface FileConfig {
+    format: LogFormat;
     dirname: string;
     filename: string;
     datePattern?: string;
@@ -18,8 +23,20 @@ interface FileConfig {
     maxSize?: string;
     maxFiles?: string;
 }
-interface LoggerConfig {
+interface LevelRule {
+    match: Record<string, unknown> & {
+        context?: string;
+    };
     level: LogLevel;
+}
+interface LevelConfigObject {
+    default: LogLevel;
+    rules?: LevelRule[];
+}
+type LevelConfig = LogLevel | LevelConfigObject;
+interface LoggerConfig {
+    level: LevelConfig;
+    console: ConsoleConfig;
     file?: FileConfig;
 }
 type LoggerContext = Record<string, unknown>;
@@ -29,6 +46,7 @@ type LevelOverrideMatch<TContext extends LoggerContext> = Partial<TContext> & {
 interface LevelOverride<TContext extends LoggerContext> {
     match: LevelOverrideMatch<TContext>;
     level: LogLevel;
+    readonly?: boolean;
 }
 type Meta = object | (() => object);
 
@@ -46,7 +64,7 @@ declare class Logger<TContext extends LoggerContext = LoggerContext> {
     for(context: string): Logger<TContext>;
     getStore(): LoggerStore<TContext>;
     setLevelOverride(match: LevelOverrideMatch<TContext>, level: LogLevel): void;
-    removeLevelOverride(match: LevelOverrideMatch<TContext>): void;
+    removeLevelOverride(match: LevelOverrideMatch<TContext>): boolean;
     clearLevelOverrides(): void;
     getLevelOverrides(): LevelOverride<TContext>[];
     profile(id: string, meta?: object): void;
@@ -102,4 +120,8 @@ interface MaskSecretsOptions {
 declare function maskSecrets(obj: unknown, options?: MaskSecretsOptions): unknown;
 declare function createMasker(options?: MaskSecretsOptions): (obj: unknown) => unknown;
 
-export { type FileConfig, LOG_LEVELS, type LevelOverride, type LevelOverrideMatch, type LogLevel, Logger, type LoggerConfig, type LoggerContext, LoggerStore, type MaskSecretsOptions, type Meta, type RequestIdOptions, type SingletonLogger, type TimingResult, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, generateRequestId, getOrGenerateRequestId, isValidLogLevel, maskSecrets, measureAsync, measureSync };
+declare function flattenObject(obj: Record<string, unknown>, prefix?: string): Record<string, unknown>;
+declare function formatLogfmtValue(value: unknown): string;
+declare function formatLogfmt(data: Record<string, unknown>): string;
+
+export { type ConsoleConfig, type FileConfig, LOG_LEVELS, type LevelConfig, type LevelConfigObject, type LevelOverride, type LevelOverrideMatch, type LevelRule, type LogFormat, type LogLevel, Logger, type LoggerConfig, type LoggerContext, LoggerStore, type MaskSecretsOptions, type Meta, type RequestIdOptions, type SingletonLogger, type TimingResult, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatLogfmt, formatLogfmtValue, generateRequestId, getOrGenerateRequestId, isValidLogLevel, maskSecrets, measureAsync, measureSync };