@beethovn/logging 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Beethovn Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,506 @@
+# @beethovn/logging
+
+Structured logging with correlation tracking for the Beethovn monorepo.
+
+## Features
+
+- **Structured Logging**: JSON-formatted logs for easy parsing and analysis
+- **Correlation Tracking**: Automatic correlation ID propagation across async operations
+- **Context Management**: Track user ID, tenant ID, and custom context fields
+- **Error Integration**: Seamless integration with `@beethovn/errors` package
+- **Multiple Log Levels**: DEBUG, INFO, WARN, ERROR with priority filtering
+- **Transport System**: Flexible output to console, files, or custom destinations
+- **Child Loggers**: Create context-specific loggers with shared configuration
+
+## Installation
+
+```bash
+pnpm add @beethovn/logging
+```
+
+## Quick Start
+
+```typescript
+import { Logger, LogLevel } from '@beethovn/logging';
+
+const logger = new Logger({
+  level: LogLevel.INFO,
+  service: 'payment-service',
+  json: true,
+});
+
+logger.info('Payment processed', { paymentId: '123', amount: 100 });
+```
+
+## Core Concepts
+
+### Log Levels
+
+```typescript
+enum LogLevel {
+  DEBUG = 'debug',  // Detailed debugging information
+  INFO = 'info',    // General informational messages
+  WARN = 'warn',    // Warning messages
+  ERROR = 'error',  // Error messages
+}
+```
+
+### Structured Log Entry
+
+Every log entry includes:
+
+```typescript
+interface LogEntry {
+  timestamp: string;        // ISO 8601 timestamp
+  level: LogLevel;          // Log level
+  message: string;          // Log message
+  service?: string;         // Service name
+  correlationId?: string;   // Request correlation ID
+  userId?: string;          // User ID from context
+  tenantId?: string;        // Tenant ID from context
+  metadata?: Record<string, unknown>;  // Additional data
+  error?: {                 // Error details (if present)
+    name: string;
+    code: string;
+    message: string;
+    stack?: string;
+    metadata?: Record<string, unknown>;
+  };
+}
+```
+
+## Usage Examples
+
+### Basic Logging
+
+```typescript
+const logger = new Logger({
+  level: LogLevel.INFO,
+  service: 'user-service',
+});
+
+logger.debug('User lookup started', { userId: '123' });
+logger.info('User authenticated', { userId: '123' });
+logger.warn('Rate limit approaching', { remaining: 10 });
+logger.error('Database connection failed');
+```
+
+### Error Logging
+
+```typescript
+import { ErrorFactory } from '@beethovn/errors';
+
+try {
+  await processPayment(paymentId);
+} catch (error: unknown) {
+  const err = ErrorFactory.fromUnknown(error, 'processPayment');
+  logger.error('Payment processing failed', err, { paymentId });
+}
+```
+
+### Correlation Tracking
+
+```typescript
+import { CorrelationContextManager } from '@beethovn/logging';
+
+// In your request handler
+const correlationId = CorrelationContextManager.generateCorrelationId();
+
+CorrelationContextManager.run(
+  {
+    correlationId,
+    userId: req.user.id,
+    tenantId: req.tenant.id,
+  },
+  async () => {
+    // All logs within this context automatically include correlation data
+    logger.info('Processing request');
+    await service.execute();
+    logger.info('Request completed');
+  }
+);
+```
+
+### Child Loggers
+
+```typescript
+const mainLogger = new Logger({ service: 'api-server' });
+
+// Create specialized logger for payment operations
+const paymentLogger = mainLogger.child({ service: 'payment-processor' });
+
+paymentLogger.info('Payment started', { paymentId: '123' });
+// Logs with service: 'payment-processor'
+```
+
+### Custom Transports
+
+```typescript
+import { Logger, type LogTransport, type LogEntry } from '@beethovn/logging';
+
+class CustomTransport implements LogTransport {
+  log(entry: LogEntry): void {
+    // Send to external logging service
+    externalService.send(entry);
+  }
+}
+
+const logger = new Logger();
+logger.addTransport(new CustomTransport());
+```
+
+### Console Transport
+
+```typescript
+import { Logger, ConsoleTransport } from '@beethovn/logging';
+
+const logger = new Logger({ json: false }); // Disable default JSON output
+logger.addTransport(new ConsoleTransport({
+  json: false,      // Human-readable format
+  colorize: true,   // ANSI color codes
+}));
+
+logger.info('User logged in', { userId: '123' });
+// Output: 2024-01-01T12:00:00.000Z [INFO] user-service User logged in
+//   Metadata: { "userId": "123" }
+```
+
+## Correlation Context Manager
+
+The `CorrelationContextManager` uses Node.js `AsyncLocalStorage` to maintain context across async operations without explicit parameter passing.
+
+### API
+
+```typescript
+class CorrelationContextManager {
+  // Run code with correlation context
+  static run<T>(context: LogContext, fn: () => T): T;
+  
+  // Get current context
+  static getContext(): LogContext | undefined;
+  
+  // Get correlation ID from context
+  static getCorrelationId(): string | undefined;
+  
+  // Get user ID from context
+  static getUserId(): string | undefined;
+  
+  // Get tenant ID from context
+  static getTenantId(): string | undefined;
+  
+  // Update current context
+  static updateContext(updates: Partial<LogContext>): void;
+  
+  // Generate new correlation ID
+  static generateCorrelationId(): string;
+}
+```
+
+### Express Middleware Example
+
+```typescript
+import { CorrelationContextManager } from '@beethovn/logging';
+
+app.use((req, res, next) => {
+  const correlationId = 
+    req.headers['x-correlation-id'] as string ||
+    CorrelationContextManager.generateCorrelationId();
+  
+  CorrelationContextManager.run(
+    {
+      correlationId,
+      userId: req.user?.id,
+      tenantId: req.tenant?.id,
+    },
+    () => next()
+  );
+});
+```
+
+### Event Handler Example
+
+```typescript
+eventBus.on('payment.created', async (event) => {
+  CorrelationContextManager.run(
+    {
+      correlationId: event.correlationId,
+      userId: event.userId,
+    },
+    async () => {
+      logger.info('Processing payment event', { paymentId: event.paymentId });
+      await processPayment(event);
+      logger.info('Payment event processed');
+    }
+  );
+});
+```
+
+## Integration with @beethovn/errors
+
+The logger automatically extracts and formats error details from `BeethovnError` instances:
+
+```typescript
+import { ValidationError } from '@beethovn/errors';
+
+const error = new ValidationError('Invalid email format', 'email');
+logger.error('Validation failed', error, { userId: '123' });
+
+// Log output includes:
+// {
+//   "level": "error",
+//   "message": "Validation failed",
+//   "error": {
+//     "name": "ValidationError",
+//     "code": "VALIDATION_ERROR",
+//     "message": "Invalid email format",
+//     "stack": "...",
+//     "metadata": { "field": "email" }
+//   },
+//   "metadata": { "userId": "123" }
+// }
+```
+
+## Configuration
+
+### Logger Config
+
+```typescript
+interface LoggerConfig {
+  level: LogLevel;          // Minimum log level (default: INFO)
+  service: string;          // Service name (default: 'beethovn')
+  json: boolean;            // JSON output format (default: true)
+  timestamps: boolean;      // Include timestamps (default: true)
+  colorize: boolean;        // ANSI color codes (default: false)
+}
+```
+
+### Log Context
+
+```typescript
+interface LogContext {
+  correlationId?: string;   // Request correlation ID
+  userId?: string;          // Authenticated user ID
+  tenantId?: string;        // Multi-tenant ID
+  service?: string;         // Service name override
+  [key: string]: unknown;   // Custom fields
+}
+```
+
+## Best Practices
+
+### 1. Use Appropriate Log Levels
+
+```typescript
+logger.debug('Cache hit', { key });           // Development debugging
+logger.info('User registered', { userId });   // Business events
+logger.warn('Cache miss', { key });           // Potential issues
+logger.error('Database error', err);          // Errors requiring attention
+```
+
+### 2. Include Structured Metadata
+
+```typescript
+// ✅ Good: Structured metadata
+logger.info('Order placed', {
+  orderId: '123',
+  userId: '456',
+  total: 99.99,
+  items: 3,
+});
+
+// ❌ Bad: Unstructured string
+logger.info(`Order 123 placed by user 456 for $99.99`);
+```
+
+### 3. Always Use Correlation Context
+
+```typescript
+// ✅ Good: Context-wrapped handler
+app.post('/orders', (req, res) => {
+  CorrelationContextManager.run(
+    {
+      correlationId: req.headers['x-correlation-id'] || generateId(),
+      userId: req.user.id,
+    },
+    async () => {
+      await createOrder(req.body);
+    }
+  );
+});
+
+// ❌ Bad: No correlation tracking
+app.post('/orders', async (req, res) => {
+  await createOrder(req.body);
+});
+```
+
+### 4. Create Service-Specific Loggers
+
+```typescript
+// ✅ Good: Service-specific logger
+const paymentLogger = new Logger({ service: 'payment-service' });
+
+// ❌ Bad: Generic logger everywhere
+const logger = new Logger({ service: 'app' });
+```
+
+### 5. Log Errors with Context
+
+```typescript
+// ✅ Good: Error with context
+try {
+  await operation();
+} catch (error: unknown) {
+  const err = ErrorFactory.fromUnknown(error);
+  logger.error('Operation failed', err, { operationId, userId });
+}
+
+// ❌ Bad: Generic error log
+try {
+  await operation();
+} catch (error) {
+  logger.error('Error occurred', error);
+}
+```
+
+## Log Output Examples
+
+### JSON Output (Default)
+
+```json
+{
+  "timestamp": "2024-01-01T12:00:00.000Z",
+  "level": "info",
+  "message": "Payment processed",
+  "service": "payment-service",
+  "correlationId": "cor-1704110400000-a1b2c3d4",
+  "userId": "user-123",
+  "tenantId": "tenant-456",
+  "metadata": {
+    "paymentId": "pay-789",
+    "amount": 99.99,
+    "currency": "USD"
+  }
+}
+```
+
+### Formatted Output
+
+```
+2024-01-01T12:00:00.000Z [INFO] payment-service (cor-1704110400000-a1b2c3d4) Payment processed
+  Metadata: {
+    "paymentId": "pay-789",
+    "amount": 99.99,
+    "currency": "USD"
+  }
+```
+
+### Error Output
+
+```json
+{
+  "timestamp": "2024-01-01T12:00:00.000Z",
+  "level": "error",
+  "message": "Payment processing failed",
+  "service": "payment-service",
+  "correlationId": "cor-1704110400000-a1b2c3d4",
+  "metadata": {
+    "paymentId": "pay-789"
+  },
+  "error": {
+    "name": "DatabaseError",
+    "code": "DATABASE_ERROR",
+    "message": "Connection timeout",
+    "stack": "DatabaseError: Connection timeout\n    at ...",
+    "metadata": {
+      "operation": "insert",
+      "table": "payments"
+    }
+  }
+}
+```
+
+## Testing
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { Logger, LogLevel } from '@beethovn/logging';
+
+describe('MyService', () => {
+  it('should log operations', () => {
+    const logger = new Logger({ json: true });
+    const logSpy = vi.spyOn(console, 'log');
+    
+    logger.info('Operation completed', { id: '123' });
+    
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining('"message":"Operation completed"')
+    );
+  });
+});
+```
+
+## Migration Guide
+
+### From console.log
+
+```typescript
+// Before
+console.log('User logged in:', userId);
+
+// After
+logger.info('User logged in', { userId });
+```
+
+### From winston/bunyan
+
+```typescript
+// Before (winston)
+const logger = winston.createLogger({
+  transports: [new winston.transports.Console()],
+});
+
+// After
+const logger = new Logger({
+  service: 'my-service',
+});
+logger.addTransport(new ConsoleTransport());
+```
+
+## Performance Considerations
+
+- Log level filtering happens before serialization (zero overhead for filtered logs)
+- JSON serialization only occurs for logs that will be output
+- Correlation context uses `AsyncLocalStorage` (minimal overhead)
+- Child loggers share transports (no duplication)
+
+## TypeScript Support
+
+Full TypeScript support with strict types:
+
+```typescript
+import type { LogEntry, LogContext, LoggerConfig } from '@beethovn/logging';
+
+const config: LoggerConfig = {
+  level: LogLevel.INFO,
+  service: 'my-service',
+  json: true,
+  timestamps: true,
+  colorize: false,
+};
+
+const context: LogContext = {
+  correlationId: 'cor-123',
+  userId: 'user-456',
+};
+```
+
+## License
+
+MIT
+
+---
+
+**Package Version:** 1.0.0  
+**Dependencies:** @beethovn/errors  
+**Node Version:** >= 18.0.0

package/dist/core/CorrelationContextManager.d.ts

@@ -0,0 +1,83 @@
+import type { LogContext } from './types.js';
+/**
+ * Manages correlation context across async operations
+ *
+ * Uses Node.js AsyncLocalStorage to maintain context without
+ * explicitly passing it through every function call.
+ */
+export declare class CorrelationContextManager {
+    private static storage;
+    /**
+     * Run a function with a specific correlation context
+     *
+     * @param context - The context to set
+     * @param fn - The function to run with this context
+     * @returns The result of the function
+     *
+     * @example
+     * ```typescript
+     * await CorrelationContextManager.run(
+     *   { correlationId: 'req-123', userId: 'user-456' },
+     *   async () => {
+     *     // This and all nested async calls will have access to the context
+     *     await processRequest();
+     *   }
+     * );
+     * ```
+     */
+    static run<T>(context: LogContext, fn: () => T): T;
+    /**
+     * Get the current correlation context
+     *
+     * @returns The current context or undefined if not in a context
+     *
+     * @example
+     * ```typescript
+     * const context = CorrelationContextManager.getContext();
+     * console.log(context?.correlationId); // 'req-123'
+     * ```
+     */
+    static getContext(): LogContext | undefined;
+    /**
+     * Get correlation ID from current context
+     *
+     * @returns Correlation ID or undefined
+     */
+    static getCorrelationId(): string | undefined;
+    /**
+     * Get user ID from current context
+     *
+     * @returns User ID or undefined
+     */
+    static getUserId(): string | undefined;
+    /**
+     * Get tenant ID from current context
+     *
+     * @returns Tenant ID or undefined
+     */
+    static getTenantId(): string | undefined;
+    /**
+     * Update the current context with new values
+     *
+     * @param updates - Partial context to merge with current
+     *
+     * @example
+     * ```typescript
+     * CorrelationContextManager.updateContext({ userId: 'user-789' });
+     * ```
+     */
+    static updateContext(updates: Partial<LogContext>): void;
+    /**
+     * Generate a new correlation ID
+     *
+     * @returns A new correlation ID in format: cor-{timestamp}-{random}
+     *
+     * @example
+     * ```typescript
+     * const id = CorrelationContextManager.generateCorrelationId();
+     * // 'cor-1704240000000-a1b2c3d4'
+     * ```
+     */
+    static generateCorrelationId(): string;
+}
+//# sourceMappingURL=CorrelationContextManager.d.ts.map

package/dist/core/CorrelationContextManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CorrelationContextManager.d.ts","sourceRoot":"","sources":["../../src/core/CorrelationContextManager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;GAKG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAuC;IAE7D;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAIlD;;;;;;;;;;OAUG;IACH,MAAM,CAAC,UAAU,IAAI,UAAU,GAAG,SAAS;IAI3C;;;;OAIG;IACH,MAAM,CAAC,gBAAgB,IAAI,MAAM,GAAG,SAAS;IAI7C;;;;OAIG;IACH,MAAM,CAAC,SAAS,IAAI,MAAM,GAAG,SAAS;IAItC;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,MAAM,GAAG,SAAS;IAIxC;;;;;;;;;OASG;IACH,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;IAOxD;;;;;;;;;;OAUG;IACH,MAAM,CAAC,qBAAqB,IAAI,MAAM;CAKvC"}

package/dist/core/CorrelationContextManager.js

@@ -0,0 +1,102 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Manages correlation context across async operations
+ *
+ * Uses Node.js AsyncLocalStorage to maintain context without
+ * explicitly passing it through every function call.
+ */
+export class CorrelationContextManager {
+    static storage = new AsyncLocalStorage();
+    /**
+     * Run a function with a specific correlation context
+     *
+     * @param context - The context to set
+     * @param fn - The function to run with this context
+     * @returns The result of the function
+     *
+     * @example
+     * ```typescript
+     * await CorrelationContextManager.run(
+     *   { correlationId: 'req-123', userId: 'user-456' },
+     *   async () => {
+     *     // This and all nested async calls will have access to the context
+     *     await processRequest();
+     *   }
+     * );
+     * ```
+     */
+    static run(context, fn) {
+        return this.storage.run(context, fn);
+    }
+    /**
+     * Get the current correlation context
+     *
+     * @returns The current context or undefined if not in a context
+     *
+     * @example
+     * ```typescript
+     * const context = CorrelationContextManager.getContext();
+     * console.log(context?.correlationId); // 'req-123'
+     * ```
+     */
+    static getContext() {
+        return this.storage.getStore();
+    }
+    /**
+     * Get correlation ID from current context
+     *
+     * @returns Correlation ID or undefined
+     */
+    static getCorrelationId() {
+        return this.getContext()?.correlationId;
+    }
+    /**
+     * Get user ID from current context
+     *
+     * @returns User ID or undefined
+     */
+    static getUserId() {
+        return this.getContext()?.userId;
+    }
+    /**
+     * Get tenant ID from current context
+     *
+     * @returns Tenant ID or undefined
+     */
+    static getTenantId() {
+        return this.getContext()?.tenantId;
+    }
+    /**
+     * Update the current context with new values
+     *
+     * @param updates - Partial context to merge with current
+     *
+     * @example
+     * ```typescript
+     * CorrelationContextManager.updateContext({ userId: 'user-789' });
+     * ```
+     */
+    static updateContext(updates) {
+        const current = this.getContext();
+        if (current) {
+            Object.assign(current, updates);
+        }
+    }
+    /**
+     * Generate a new correlation ID
+     *
+     * @returns A new correlation ID in format: cor-{timestamp}-{random}
+     *
+     * @example
+     * ```typescript
+     * const id = CorrelationContextManager.generateCorrelationId();
+     * // 'cor-1704240000000-a1b2c3d4'
+     * ```
+     */
+    static generateCorrelationId() {
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).substring(2, 10);
+        return `cor-${timestamp}-${random}`;
+    }
+}
+//# sourceMappingURL=CorrelationContextManager.js.map