@ricdotnet/logger 0.3.3 → 0.4.1

package/README.md

@@ -0,0 +1,284 @@
+# @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)

package/dist/formatters/json.d.ts

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

package/dist/formatters/json.js

@@ -0,0 +1,5 @@
+export class JsonFormatter {
+    format(entry) {
+        return JSON.stringify(entry);
+    }
+}

package/dist/formatters/pretty.d.ts

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

package/dist/formatters/pretty.js

@@ -0,0 +1,7 @@
+export class PrettyFormatter {
+    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}`;
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,6 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Logger = void 0;
-var Logger_1 = require("./src/Logger");
-Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return Logger_1.Logger; } });
-//# sourceMappingURL=index.js.map
+// Main exports
+export { Logger } from './logger';
+export { JsonFormatter } from './formatters/json';
+export { PrettyFormatter } from './formatters/pretty';

package/dist/logger.d.ts

@@ -0,0 +1,34 @@
+import { Formatter, LogLevel, Transport } from './types';
+type TOptions = {
+    name?: string;
+    level?: LogLevel;
+    transports?: Transport[];
+    context?: Record<string, unknown>;
+    formatter?: Formatter;
+    redact?: string[];
+};
+export declare class Logger {
+    private name;
+    private level;
+    private transports;
+    private context;
+    private formatter;
+    private redact;
+    constructor(options?: TOptions);
+    trace(message: string, context?: {}): void;
+    debug(message: string, context?: {}): void;
+    info(message: string, context?: {}): void;
+    warn(message: string, context?: {}): void;
+    error(message: string, context?: {}): void;
+    fatal(message: string, context?: {}): void;
+    log(level: LogLevel, message: string, context?: {}): void;
+    child(name: String, context?: Record<string, unknown>): Logger;
+    get _name(): string;
+    get _level(): LogLevel;
+    get _transports(): Transport[];
+    get _context(): Record<string, unknown>;
+    get _formatter(): Formatter;
+    get _redact(): string[];
+    private shouldLog;
+}
+export {};

package/dist/logger.js

@@ -0,0 +1,95 @@
+import { JsonFormatter } from './formatters/json';
+import { ConsoleTransport } from './transports/console';
+export class Logger {
+    name;
+    level = 'info';
+    transports = [new ConsoleTransport()];
+    context;
+    formatter;
+    redact;
+    constructor(options = {}) {
+        this.name = options.name || 'default';
+        this.level = options.level || '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);
+    }
+    debug(message, context = {}) {
+        this.log('debug', message, context);
+    }
+    info(message, context = {}) {
+        this.log('info', message, context);
+    }
+    warn(message, context = {}) {
+        this.log('warn', message, context);
+    }
+    error(message, context = {}) {
+        this.log('error', message, context);
+    }
+    fatal(message, context = {}) {
+        this.log('fatal', message, context);
+    }
+    log(level, message, context = {}) {
+        if (!this.shouldLog(level)) {
+            return;
+        }
+        const mergedContext = {
+            ...this.context,
+            ...context,
+        };
+        this.redact.forEach((key) => {
+            if (mergedContext[key]) {
+                mergedContext[key] = '******';
+            }
+        });
+        const entry = {
+            name: this.name,
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+            ...mergedContext,
+        };
+        const output = this.formatter.format(entry);
+        for (const transport of this.transports) {
+            transport.write(entry, output);
+        }
+    }
+    child(name, context = {}) {
+        return new Logger({
+            name: `${this.name}.${name}`,
+            level: this.level,
+            transports: this.transports,
+            formatter: this.formatter,
+            redact: this.redact,
+            context: {
+                ...this.context,
+                ...context,
+            },
+        });
+    }
+    get _name() {
+        return this.name;
+    }
+    get _level() {
+        return this.level;
+    }
+    get _transports() {
+        return this.transports;
+    }
+    get _context() {
+        return this.context;
+    }
+    get _formatter() {
+        return this.formatter;
+    }
+    get _redact() {
+        return this.redact;
+    }
+    shouldLog(level) {
+        return this.level === 'debug' || level === this.level;
+    }
+}

package/dist/transports/console.d.ts

@@ -0,0 +1,5 @@
+import { LogEntry, Transport } from '../types';
+export declare class ConsoleTransport implements Transport {
+    write(entry: LogEntry, formatted: string): void;
+    close?(): void | Promise<void>;
+}

package/dist/transports/console.js

@@ -0,0 +1,11 @@
+export class ConsoleTransport {
+    write(entry, formatted) {
+        const output = entry.level === 'error' || entry.level === 'fatal'
+            ? process.stderr
+            : process.stdout;
+        output.write(`${formatted}\n`);
+    }
+    close() {
+        throw new Error('Method not implemented.');
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,14 @@
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    context?: Record<string, unknown>;
+}
+export interface Formatter {
+    format(entry: LogEntry): string;
+}
+export interface Transport {
+    write(entry: LogEntry, formatted: string): void | Promise<void>;
+    close?(): void | Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,35 +1,45 @@
-{
-  "name": "@ricdotnet/logger",
-  "version": "0.3.3",
-  "description": "A logger utility for my personal projects.",
-  "main": "index.js",
-  "scripts": {
-    "start": "node dist/index.js",
-    "dev": "ts-node index.ts",
-    "build": "rm -rf ./dist && tsc",
-    "test": "jest ./"
-  },
-  "keywords": [
-    "logger",
-    "logs",
-    "console.log",
-    "log",
-    "logjs",
-    "logts",
-    "logger4ts",
-    "logger4js"
-  ],
-  "author": "ricdotnet <me@rrocha.uk> https://ricr.dev",
-  "repository": "https://github.com/ricdotnet/logger-utility",
-  "license": "ISC",
-  "devDependencies": {
-    "@types/jest": "^27.4.1",
-    "@types/node": "^20.11.19",
-    "jest": "^27.5.1",
-    "prettier": "3.1.1",
-    "ts-jest": "^27.1.4",
-    "ts-node": "^10.7.0",
-    "typescript": "^4.6.3"
-  },
-  "packageManager": "yarn@3.6.4"
-}
+{
+  "name": "@ricdotnet/logger",
+  "version": "0.4.1",
+  "description": "A logger utility for my personal projects",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clear": "rm -rf dist",
+    "prepublishOnly": "npm run clear && npm run build",
+    "test": "vitest"
+  },
+  "keywords": [
+    "logger",
+    "logs",
+    "console.log",
+    "log",
+    "logjs",
+    "logts",
+    "logger4ts",
+    "logger4js"
+  ],
+  "author": "ricdotnet <me@rrocha.uk> https://ricr.dev",
+  "repository": {
+    "url": "git+https://github.com/ricdotnet/logger.git"
+  },
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "@vitest/coverage-v8": "^5.0.5",
+    "prettier": "3.9.10",
+    "typescript": "7.0.2",
+    "vitest": "^5.0.5"
+  }
+}