@ricdotnet/logger 0.4.1 → 0.4.3

package/README.md

@@ -1,284 +1,287 @@
-# @ricdotnet/logger
-
-A lightweight, flexible logging library for TypeScript/JavaScript projects with support for custom formatters and transports.
-
-## Features
-
-- 🎯 **Simple API** - Easy to use with sensible defaults
-- 📦 **Modular** - Swap formatters and transports to suit your needs
-- 🎨 **Multiple Formatters** - JSON and Pretty formatters included
-- 📤 **Extensible Transports** - Console transport included, create your own
-- 🌳 **Contextual Logging** - Add context that propagates through child loggers
-- 📝 **Full TypeScript Support** - Built with TypeScript for type safety
-
-## Installation
-
-```bash
-npm install @ricdotnet/logger
-```
-
-## Quick Start
-
-```typescript
-import { Logger } from '@ricdotnet/logger';
-
-const logger = new Logger();
-
-logger.info('Application started');
-logger.error('Something went wrong!');
-```
-
-## Usage
-
-### Basic Logging
-
-The logger provides two main methods for logging:
-
-```typescript
-import { Logger } from '@ricdotnet/logger';
-
-const logger = new Logger();
-
-// Log at info level
-logger.info('User logged in');
-
-// Log at error level
-logger.error('Database connection failed');
-
-// Generic log method with level specification
-logger.log('warn', 'High memory usage detected');
-```
-
-### Log Levels
-
-The logger supports the following log levels:
-
-- `debug` - Detailed debug information
-- `info` - General informational messages
-- `warn` - Warning messages
-- `error` - Error messages
-- `fatal` - Fatal error messages (rarely recoverable)
-
-### Adding Context
-
-You can pass an object as the second argument to add context to your logs:
-
-```typescript
-logger.info('User action', {
-  userId: 123,
-  action: 'profile_update',
-  ip: '192.168.1.1',
-});
-```
-
-### Configuration
-
-The logger accepts an options object in its constructor:
-
-```typescript
-import { Logger } from '@ricdotnet/logger';
-import { PrettyFormatter } from '@ricdotnet/logger';
-
-const logger = new Logger({
-  // Set the minimum log level
-  level: 'debug',
-
-  // Specify custom formatters (defaults to JsonFormatter)
-  formatter: new PrettyFormatter(),
-
-  // Add custom transports (defaults to Console transport)
-  transports: [
-    // Your custom transports here
-  ],
-
-  // Add default context that's included in all logs
-  context: {
-    service: 'api',
-    version: '1.0.0',
-  },
-});
-```
-
-### Available Formatters
-
-#### JsonFormatter (default)
-
-Outputs logs as JSON, perfect for log aggregation services:
-
-```typescript
-import { Logger } from '@ricdotnet/logger';
-
-const logger = new Logger();
-// Output: {"timestamp":"2024-11-01T10:30:45.123Z","level":"info","message":"User logged in"}
-```
-
-#### PrettyFormatter
-
-Human-readable format, great for development:
-
-```typescript
-import { Logger, PrettyFormatter } from '@ricdotnet/logger';
-
-const logger = new Logger({
-  formatter: new PrettyFormatter(),
-});
-
-logger.info('User logged in', { userId: 123 });
-// Output: [11/1/2024, 10:30:45 AM] [INFO] User logged in {"userId":123}
-```
-
-### Using Transports
-
-Transports determine where logs are written. The default console transport writes to `stdout` for info/debug/warn and `stderr` for error/fatal messages.
-
-#### Console Transport (default)
-
-```typescript
-import { Logger, ConsoleTransport } from '@ricdotnet/logger';
-
-const logger = new Logger({
-  transports: [new ConsoleTransport()],
-});
-```
-
-#### Creating Custom Transports
-
-Implement the `Transport` interface to create your own:
-
-```typescript
-import { Logger, Transport, LogEntry } from '@ricdotnet/logger';
-
-class FileTransport implements Transport {
-  constructor(private filepath: string) {}
-
-  write(entry: LogEntry, formatted: string): void {
-    // Write to file
-    fs.appendFileSync(this.filepath, formatted + '\n');
-  }
-
-  close(): void {
-    // Cleanup if needed
-  }
-}
-
-const logger = new Logger({
-  transports: [new ConsoleTransport(), new FileTransport('./logs/app.log')],
-});
-```
-
-### Child Loggers
-
-Create child loggers that inherit configuration and context from their parent:
-
-```typescript
-const logger = new Logger({
-  context: { service: 'api' },
-});
-
-// Child logger inherits parent context
-const requestLogger = logger.child({
-  requestId: 'abc-123',
-  userId: 456,
-});
-
-requestLogger.info('Request received');
-// Logs include: { service: 'api', requestId: 'abc-123', userId: 456, ... }
-```
-
-This is useful for associating logs with specific requests, operations, or components.
-
-## Complete Example
-
-```typescript
-import { Logger, PrettyFormatter, type LogEntry } from '@ricdotnet/logger';
-
-// Create a custom file transport
-class FileTransport {
-  constructor(private filepath: string) {}
-
-  write(entry: LogEntry, formatted: string): void {
-    // Implementation here
-  }
-}
-
-// Initialize logger
-const logger = new Logger({
-  level: 'debug',
-  formatter: new PrettyFormatter(),
-  transports: [new FileTransport('./logs/app.log')],
-  context: {
-    app: 'my-app',
-    environment: process.env.NODE_ENV,
-  },
-});
-
-// Use in your application
-const userLogger = logger.child({ module: 'users' });
-userLogger.info('Processing user registration', { email: 'user@example.com' });
-
-try {
-  // Some operation
-} catch (error) {
-  userLogger.error('Registration failed', { error: error.message });
-}
-```
-
-## API Reference
-
-### Logger
-
-#### Constructor
-
-```typescript
-constructor(options?: {
-  level?: 'debug' | 'info' | 'warn' | 'error';
-  formatter?: Formatter;
-  transports?: Transport[];
-  context?: Record<string, unknown>;
-})
-```
-
-#### Methods
-
-- `info(message: string, context?: Record<string, unknown>): void` - Log at info level
-- `error(message: string, context?: Record<string, unknown>): void` - Log at error level
-- `log(level: TLevel, message: string, context?: Record<string, unknown>): void` - Generic log method
-- `child(context?: Record<string, unknown>): Logger` - Create a child logger with inherited context
-
-### Exports
-
-```typescript
-import {
-  Logger, // Main logger class
-  PrettyFormatter, // Human-readable formatter
-  JsonFormatter, // JSON formatter
-  ConsoleTransport, // Console transport
-  // Types
-  type LogEntry,
-  type LogLevel,
-  type Formatter,
-  type Transport,
-  type TLevel,
-} from '@ricdotnet/logger';
-```
-
-## TypeScript Support
-
-All types are exported from the main package entry point:
-
-```typescript
-import type {
-  LogEntry, // The log entry object
-  LogLevel, // Union type of all levels
-  Formatter, // Transport interface
-  Transport, // Transport interface
-} from '@ricdotnet/logger';
-```
-
-## License
-
-ISC
-
-## Author
-
-ricdotnet - [ricr.dev](https://ricr.dev)
+# @ricdotnet/logger
+
+A lightweight, flexible logging library for TypeScript/JavaScript projects with support for custom formatters and transports.
+
+## Features
+
+- 🎯 **Simple API** - Easy to use with sensible defaults
+- 📦 **Modular** - Swap formatters and transports to suit your needs
+- 🎨 **Multiple Formatters** - JSON and Pretty formatters included
+- 📤 **Extensible Transports** - Console transport included, create your own
+- 🌳 **Contextual Logging** - Add context that propagates through child loggers
+- 📝 **Full TypeScript Support** - Built with TypeScript for type safety
+
+## Installation
+
+```bash
+npm install @ricdotnet/logger
+```
+
+## Quick Start
+
+```typescript
+import { Logger } from '@ricdotnet/logger';
+
+const logger = new Logger();
+
+logger.info('Application started');
+logger.error('Something went wrong!');
+```
+
+## Usage
+
+### Basic Logging
+
+The logger provides two main methods for logging:
+
+```typescript
+import { Logger } from '@ricdotnet/logger';
+
+const logger = new Logger();
+
+// Log at info level
+logger.info('User logged in');
+
+// Log at error level
+logger.error('Database connection failed');
+
+// Generic log method with level specification
+logger.log('warn', 'High memory usage detected');
+```
+
+### Log Levels
+
+The logger supports the following log levels:
+
+- `0 - TRACE` - Low-level debugging information
+- `10 - DEBUG` - Detailed debug information
+- `20 - INFO` - General informational messages
+- `30 - WARN` - Warning messages
+- `40 - ERROR` - Error messages
+- `50 - FATAL` - Fatal error messages (rarely recoverable)
+
+### Adding Context
+
+You can pass an object as the second argument to add context to your logs:
+
+```typescript
+logger.info('User action', {
+  userId: 123,
+  action: 'profile_update',
+  ip: '192.168.1.1',
+});
+```
+
+### Configuration
+
+The logger accepts an options object in its constructor:
+
+```typescript
+import { Logger, LogLevel, PrettyFormatter } from '@ricdotnet/logger';
+
+const logger = new Logger({
+  // Set the minimum log level
+  level: LogLevel.DEBUG,
+
+  // Specify custom formatters (defaults to JsonFormatter)
+  formatter: new PrettyFormatter(),
+
+  // Add custom transports (defaults to Console transport)
+  transports: [
+    // Your custom transports here
+  ],
+
+  // Add default context that's included in all logs
+  context: {
+    service: 'api',
+    version: '1.0.0',
+  },
+});
+```
+
+### Available Formatters
+
+#### JsonFormatter (default)
+
+Outputs logs as JSON, perfect for log aggregation services:
+
+```typescript
+import { Logger } from '@ricdotnet/logger';
+
+const logger = new Logger();
+// Output: {"timestamp":"2024-11-01T10:30:45.123Z","level":"info","message":"User logged in"}
+```
+
+#### PrettyFormatter
+
+Human-readable format, great for development:
+
+```typescript
+import { Logger, PrettyFormatter } from '@ricdotnet/logger';
+
+const logger = new Logger({
+  formatter: new PrettyFormatter(),
+});
+
+logger.info('User logged in', { userId: 123 });
+// Output:
+// [11/1/2024, 10:30:45 AM] [INFO] User logged in
+//   userId=123
+```
+
+### Using Transports
+
+Transports determine where logs are written. The default console transport writes to `stdout` for info/debug/warn and `stderr` for error/fatal messages.
+
+#### Console Transport (default)
+
+```typescript
+import { Logger, ConsoleTransport } from '@ricdotnet/logger';
+
+const logger = new Logger({
+  transports: [new ConsoleTransport()],
+});
+```
+
+#### Creating Custom Transports
+
+Implement the `Transport` interface to create your own:
+
+```typescript
+import { Logger, Transport, LogEntry } from '@ricdotnet/logger';
+
+class FileTransport implements Transport {
+  constructor(private filepath: string) {}
+
+  write(entry: LogEntry, formatted: string): void {
+    // Write to file
+    fs.appendFileSync(this.filepath, formatted + '\n');
+  }
+
+  close(): void {
+    // Cleanup if needed
+  }
+}
+
+const logger = new Logger({
+  transports: [new ConsoleTransport(), new FileTransport('./logs/app.log')],
+});
+```
+
+### Child Loggers
+
+Create child loggers that inherit configuration and context from their parent:
+
+```typescript
+const logger = new Logger({
+  context: { service: 'api' },
+});
+
+// Child logger inherits parent context
+const requestLogger = logger.child({
+  requestId: 'abc-123',
+  userId: 456,
+});
+
+requestLogger.info('Request received');
+// Logs include: { service: 'api', requestId: 'abc-123', userId: 456, ... }
+```
+
+This is useful for associating logs with specific requests, operations, or components.
+
+## Complete Example
+
+```typescript
+import { Logger, PrettyFormatter, type LogEntry } from '@ricdotnet/logger';
+
+// Create a custom file transport
+class FileTransport {
+  constructor(private filepath: string) {}
+
+  write(entry: LogEntry, formatted: string): void {
+    // Implementation here
+  }
+}
+
+// Initialize logger
+const logger = new Logger({
+  level: 'debug',
+  formatter: new PrettyFormatter(),
+  transports: [new FileTransport('./logs/app.log')],
+  context: {
+    app: 'my-app',
+    environment: process.env.NODE_ENV,
+  },
+});
+
+// Use in your application
+const userLogger = logger.child({ module: 'users' });
+userLogger.info('Processing user registration', { email: 'user@example.com' });
+
+try {
+  // Some operation
+} catch (error) {
+  userLogger.error('Registration failed', { error: error.message });
+}
+```
+
+## API Reference
+
+### Logger
+
+#### Constructor
+
+```typescript
+constructor(options?: {
+  level?: LogLevel;
+  formatter?: Formatter;
+  transports?: Transport[];
+  context?: Record<string, unknown>;
+})
+```
+
+#### Methods
+
+- `info(message: string, context?: Record<string, unknown>): void` - Log at info level
+- `error(message: string, context?: Record<string, unknown>): void` - Log at error level
+- `log(level: TLevel, message: string, context?: Record<string, unknown>): void` - Generic log method
+- `child(context?: Record<string, unknown>): Logger` - Create a child logger with inherited context
+
+### Exports
+
+```typescript
+import {
+  Logger, // Main logger class
+  LogLevel, // LogLevel enum containing 5 levels
+  PrettyFormatter, // Human-readable formatter
+  JsonFormatter, // JSON formatter
+  ConsoleTransport, // Console transport
+  LogLevelNames, // Map of log level names corresponding to their enum value
+  // Types
+  type LogEntry,
+  type Formatter,
+  type Transport,
+  type TLevel,
+} from '@ricdotnet/logger';
+```
+
+## TypeScript Support
+
+All types are exported from the main package entry point:
+
+```typescript
+import type {
+  LogEntry, // The log entry object
+  LogLevel, // Union type of all levels
+  Formatter, // Transport interface
+  Transport, // Transport interface
+} from '@ricdotnet/logger';
+```
+
+## License
+
+ISC
+
+## Author
+
+ricdotnet - [ricr.dev](https://ricr.dev)

package/dist/formatters/pretty.d.ts

@@ -1,4 +1,6 @@
-import type { Formatter, LogEntry } from '../types';
+import { type Formatter, type LogEntry } from '../types';
 export declare class PrettyFormatter implements Formatter {
+    private indent;
     format(entry: LogEntry): string;
+    private unwrapContext;
 }

package/dist/formatters/pretty.js

@@ -1,7 +1,20 @@
+import { LogLevelNames } from '../types';
 export class PrettyFormatter {
+    indent = 2;
     format(entry) {
         const timestamp = new Date(entry.timestamp).toLocaleString();
-        const context = entry.context ? JSON.stringify(entry.context) : '';
-        return `[${timestamp}] [${entry.level.toUpperCase()}] ${entry.message} ${context}`;
+        const context = this.unwrapContext(entry.context ?? {}).join('\n');
+        return `[${timestamp}] [${LogLevelNames[entry.level].toLocaleUpperCase()}] ${entry.message}\n${context}`;
+    }
+    unwrapContext(context, unwrapped = [], level = 1) {
+        for (const key in context) {
+            if (typeof context[key] === 'object') {
+                unwrapped.push(`${'  '.repeat(level * this.indent)}${key}`);
+                this.unwrapContext(context[key], unwrapped, level + 1);
+                continue;
+            }
+            unwrapped.push(`${'  '.repeat(level * this.indent)}${key}=${context[key]}`);
+        }
+        return unwrapped;
     }
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { Logger } from './logger';
-export type { LogEntry, LogLevel, Formatter, Transport } from './types';
+export { LogLevel, LogLevelNames } from './types';
+export type { LogEntry, Formatter, Transport } from './types';
 export { JsonFormatter } from './formatters/json';
 export { PrettyFormatter } from './formatters/pretty';

package/dist/index.js

@@ -1,4 +1,5 @@
 // Main exports
 export { Logger } from './logger';
+export { LogLevel, LogLevelNames } from './types';
 export { JsonFormatter } from './formatters/json';
 export { PrettyFormatter } from './formatters/pretty';

package/dist/logger.js

@@ -1,37 +1,38 @@
 import { JsonFormatter } from './formatters/json';
 import { ConsoleTransport } from './transports/console';
+import { LogLevel } from './types';
 export class Logger {
     name;
-    level = 'info';
+    level;
     transports = [new ConsoleTransport()];
     context;
     formatter;
     redact;
     constructor(options = {}) {
         this.name = options.name || 'default';
-        this.level = options.level || 'info';
+        this.level = options.level || LogLevel.INFO;
         this.transports = [...this.transports, ...(options.transports || [])];
         this.context = options.context || {};
         this.formatter = options.formatter || new JsonFormatter();
         this.redact = options.redact || [];
     }
     trace(message, context = {}) {
-        this.log('trace', message, context);
+        this.log(LogLevel.TRACE, message, context);
     }
     debug(message, context = {}) {
-        this.log('debug', message, context);
+        this.log(LogLevel.DEBUG, message, context);
     }
     info(message, context = {}) {
-        this.log('info', message, context);
+        this.log(LogLevel.INFO, message, context);
     }
     warn(message, context = {}) {
-        this.log('warn', message, context);
+        this.log(LogLevel.WARN, message, context);
     }
     error(message, context = {}) {
-        this.log('error', message, context);
+        this.log(LogLevel.ERROR, message, context);
     }
     fatal(message, context = {}) {
-        this.log('fatal', message, context);
+        this.log(LogLevel.FATAL, message, context);
     }
     log(level, message, context = {}) {
         if (!this.shouldLog(level)) {
@@ -51,7 +52,7 @@ export class Logger {
             timestamp: new Date().toISOString(),
             level,
             message,
-            ...mergedContext,
+            context: mergedContext,
         };
         const output = this.formatter.format(entry);
         for (const transport of this.transports) {
@@ -90,6 +91,6 @@ export class Logger {
         return this.redact;
     }
     shouldLog(level) {
-        return this.level === 'debug' || level === this.level;
+        return level >= this.level;
     }
 }

package/dist/transports/console.js

@@ -1,6 +1,7 @@
+import { LogLevel } from '../types';
 export class ConsoleTransport {
     write(entry, formatted) {
-        const output = entry.level === 'error' || entry.level === 'fatal'
+        const output = entry.level === LogLevel.ERROR || entry.level === LogLevel.FATAL
             ? process.stderr
             : process.stdout;
         output.write(`${formatted}\n`);

package/dist/types.d.ts

@@ -1,4 +1,12 @@
-export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export declare enum LogLevel {
+    TRACE = 0,
+    DEBUG = 10,
+    INFO = 20,
+    WARN = 30,
+    ERROR = 40,
+    FATAL = 50
+}
+export declare const LogLevelNames: Record<LogLevel, string>;
 export interface LogEntry {
     timestamp: string;
     level: LogLevel;

package/dist/types.js

@@ -1 +1,17 @@
-export {};
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["TRACE"] = 0] = "TRACE";
+    LogLevel[LogLevel["DEBUG"] = 10] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 20] = "INFO";
+    LogLevel[LogLevel["WARN"] = 30] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 40] = "ERROR";
+    LogLevel[LogLevel["FATAL"] = 50] = "FATAL";
+})(LogLevel || (LogLevel = {}));
+export const LogLevelNames = {
+    [LogLevel.TRACE]: 'trace',
+    [LogLevel.DEBUG]: 'debug',
+    [LogLevel.INFO]: 'info',
+    [LogLevel.WARN]: 'warn',
+    [LogLevel.ERROR]: 'error',
+    [LogLevel.FATAL]: 'fatal',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricdotnet/logger",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "A logger utility for my personal projects",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",