iLog - TypeScript Logger

A comprehensive, fully type-supported logging library for JavaScript/TypeScript projects. Easily manage API calls, performance metrics, and application logs with advanced features.

Features

• 🎯 Full TypeScript Support - Complete type safety
• 🚀 API Logging - Automatic HTTP request/response logging
• 📊 Performance Monitoring - Track operation times and memory usage
• 🔒 Sensitive Data Masking - Automatic masking of sensitive information
• 📁 Multiple Writers - Console, file, HTTP endpoint support
• 🎨 Flexible Formatting - JSON, Pretty, API-specific formatters
• 🔄 File Rotation - Automatic log file rotation
• 📦 Modular Architecture - Following separation of concerns principles
• 🪝 HTTP Interceptors - Automatic capture for Fetch, Axios, XHR
• ⚡ Middleware System - Extensible log processing pipeline

Installation

npm install @alisahindev/ilog
# or
yarn add @alisahindev/ilog

Quick Start

import { createLogger, LogLevel } from '@alisahindev/ilog';

// Basic usage
const logger = createLogger({
  level: LogLevel.INFO,
  enableConsole: true,
  enableFile: true,
  filePath: './logs/app.log'
});

logger.info('Application started');
logger.error('An error occurred', new Error('Sample error'));

API Logging

Automatic Interceptors

import { FetchInterceptor, AxiosInterceptor } from '@alisahindev/ilog';

// Automatic logging for Fetch API
const fetchInterceptor = new FetchInterceptor(logger, {
  logRequests: true,
  logResponses: true,
  maskSensitiveData: true,
  sensitiveFields: ['authorization', 'x-api-key']
});

fetchInterceptor.install();

// Now all fetch calls will be automatically logged
fetch('/api/users').then(response => response.json());

Manual API Logging

// Manual API logging
logger.logApiRequest('POST', '/api/users', {
  requestBody: { name: 'John', email: '[email protected]' },
  requestHeaders: { 'Content-Type': 'application/json' }
});

logger.logApiResponse('POST', '/api/users', 201, 250, {
  responseBody: { id: 1, name: 'John' }
});

logger.logApiError('GET', '/api/users/999', new Error('User not found'));

Performance Monitoring

// Automatic timing
const timer = logger.startTimer('database-query');
await performDatabaseQuery();
timer(); // Automatically logs duration and memory usage

// Custom performance metrics
logger.logPerformance({
  timestamp: new Date(),
  level: LogLevel.INFO,
  message: 'Batch processing completed',
  operation: 'batch-process',
  duration: 1500,
  customMetrics: {
    itemsProcessed: 100,
    successRate: 0.95
  }
});

Sensitive Data Masking

import { maskSensitiveData } from '@alisahindev/ilog';

const userData = {
  name: 'John Doe',
  email: '[email protected]',
  password: 'secret123',
  creditCard: '1234-5678-9012-3456'
};

const masked = maskSensitiveData(userData, {
  sensitiveFields: ['password', 'creditCard'],
  showFirst: 2,
  showLast: 2
});

logger.info('User data', { user: masked });
// Output: { name: 'John Doe', email: '[email protected]', password: 'se*****23', creditCard: '12**-****-****-**56' }

Context Management

// Global context
logger.setContext('requestId', 'req-123');
logger.setUserId('user-456');
logger.setSessionId('sess-789');

// Child logger with additional context
const serviceLogger = logger.child({ 
  service: 'auth',
  version: '1.2.0'
});

serviceLogger.info('Authentication successful');
// Includes all parent context + service-specific context

Middleware System

iLog provides a powerful middleware system that allows you to intercept and modify log entries before they are processed. This enables advanced logging features like filtering, enrichment, metrics collection, and rate limiting.

Built-in Middleware

Timestamp Middleware

import { TimestampMiddleware } from '@alisahindev/ilog';

const logger = createLogger();
logger.use(new TimestampMiddleware({
  format: 'iso', // 'iso', 'locale', or 'unix'
  timezone: 'Europe/Istanbul'
}));

logger.info('Message with formatted timestamp');

Filter Middleware

import { FilterMiddleware, LogLevel } from '@alisahindev/ilog';

const filterMiddleware = new FilterMiddleware({
  minLevel: LogLevel.INFO,
  maxLevel: LogLevel.ERROR,
  excludeMessages: ['debug', 'trace'],
  includeMessages: ['important'],
  excludeContextKeys: ['sensitive'],
  includeContextKeys: ['userId']
});

logger.use(filterMiddleware);

Correlation ID Middleware

import { CorrelationIdMiddleware } from '@alisahindev/ilog';

const correlationMiddleware = new CorrelationIdMiddleware({
  fieldName: 'traceId',
  generateNew: false, // true to generate new ID for each log
  idLength: 16
});

logger.use(correlationMiddleware);
logger.info('Message with correlation ID');

Metrics Middleware

import { MetricsMiddleware } from '@alisahindev/ilog';

const metricsMiddleware = new MetricsMiddleware({
  trackFrequency: true,
  frequencyWindowMinutes: 5
});

logger.use(metricsMiddleware);

// Get metrics
const metrics = metricsMiddleware.getMetrics();
console.log(metrics.totalLogs, metrics.errorCount, metrics.logFrequency);

Rate Limiting Middleware

import { RateLimitMiddleware, LogLevel } from '@alisahindev/ilog';

const rateLimitMiddleware = new RateLimitMiddleware({
  maxLogsPerSecond: 10,
  maxLogsPerMinute: 100,
  maxLogsPerHour: 1000,
  skipLevels: [LogLevel.FATAL], // Don't rate limit fatal errors
  onRateLimitExceeded: (droppedCount) => {
    console.warn(`Rate limit exceeded! Dropped ${droppedCount} logs`);
  }
});

logger.use(rateLimitMiddleware);

Custom Middleware

Function-based Middleware

import { Logger, MiddlewareFunction } from '@alisahindev/ilog';

const enrichmentMiddleware: MiddlewareFunction = async (entry, context, next) => {
  // Enrich log entry
  entry.context = {
    ...entry.context,
    environment: process.env.NODE_ENV,
    service: 'my-service',
    version: '1.0.0'
  };
  
  // Add metadata for other middleware
  context.metadata.processedAt = new Date().toISOString();
  
  // Continue to next middleware
  await next();
};

logger.use(enrichmentMiddleware);

Class-based Middleware

import { LogMiddleware, LogEntry, MiddlewareContext } from '@alisahindev/ilog';

class CustomMiddleware implements LogMiddleware {
  name = 'CustomMiddleware';
  
  async execute(
    entry: LogEntry,
    context: MiddlewareContext,
    next: () => Promise<void> | void
  ): Promise<void> {
    // Custom processing logic
    if (entry.level >= LogLevel.ERROR) {
      entry.context = {
        ...entry.context,
        alerting: true
      };
    }
    
    await next();
  }
}

logger.use(new CustomMiddleware());

Middleware Pipeline Management

// Add middleware
logger.use(new TimestampMiddleware());
logger.use(new CorrelationIdMiddleware());

// Remove specific middleware
logger.removeMiddleware('TimestampMiddleware');

// Clear all middleware
logger.clearMiddlewares();

// Child loggers inherit parent middleware
const childLogger = logger.child({ component: 'auth' });

Middleware Configuration at Logger Creation

import { 
  Logger, 
  TimestampMiddleware, 
  FilterMiddleware,
  LogLevel 
} from '@alisahindev/ilog';

const logger = new Logger({
  level: LogLevel.INFO,
  enableConsole: true,
  middlewares: [
    new TimestampMiddleware({ format: 'iso' }),
    new FilterMiddleware({ minLevel: LogLevel.INFO })
  ]
});

Async Middleware Support

const asyncMiddleware: MiddlewareFunction = async (entry, context, next) => {
  // Async operations are fully supported
  await someAsyncOperation();
  
  entry.context = {
    ...entry.context,
    asyncProcessed: true
  };
  
  await next();
};

logger.use(asyncMiddleware);

Custom Writers

import { HttpWriter, FileWriter, BufferedWriter } from '@alisahindev/ilog';

const logger = createLogger({
  customWriters: [
    // Send logs to HTTP endpoint
    new HttpWriter('https://logs.yourservice.com/api/logs', {
      'Authorization': 'Bearer your-token'
    }),
    
    // Buffered file writing
    new BufferedWriter(
      new FileWriter('./logs/buffered.log'),
      100, // Buffer size
      5000 // Flush interval (ms)
    )
  ]
});

Advanced Configuration

import { Logger, LogLevel, JsonFormatter, ApiFormatter } from '@alisahindev/ilog';

const logger = new Logger({
  level: LogLevel.DEBUG,
  enableConsole: true,
  enableFile: true,
  filePath: './logs/app.log',
  maxFileSize: 10, // MB
  maxFiles: 5,
  formatter: new JsonFormatter(), // or ApiFormatter, PrettyFormatter
  enableApiLogging: true,
  enablePerformanceLogging: true,
  sensitiveFields: ['password', 'token', 'ssn', 'creditCard']
});

Log Levels

logger.debug('Debug message');    // LogLevel.DEBUG
logger.info('Info message');      // LogLevel.INFO  
logger.warn('Warning message');   // LogLevel.WARN
logger.error('Error message');    // LogLevel.ERROR
logger.fatal('Fatal message');    // LogLevel.FATAL

Formatters

Pretty Formatter (Development)

import { PrettyFormatter } from '@alisahindev/ilog';

const logger = createLogger({
  formatter: new PrettyFormatter()
});
// Colorful, human-readable output

JSON Formatter (Production)

import { JsonFormatter } from '@alisahindev/ilog';

const logger = createLogger({
  formatter: new JsonFormatter()
});
// Structured JSON output for log aggregation

API Formatter

import { ApiFormatter } from '@alisahindev/ilog';

const logger = createLogger({
  formatter: new ApiFormatter()
});
// Specialized formatting for API calls

Best Practices

Structured Logging

// ✅ Good - Structured data
logger.info('User login successful', {
  userId: '123',
  ip: '192.168.1.1',
  userAgent: 'Mozilla/5.0...'
});

// ❌ Avoid - String interpolation
logger.info(`User ${userId} logged in from ${ip}`);

Service-Specific Loggers

class UserService {
  private logger = rootLogger.child({ service: 'user-service' });
  
  async createUser(userData: any) {
    const timer = this.logger.startTimer('create-user');
    try {
      this.logger.info('Creating new user', { email: userData.email });
      // ... user creation logic
      this.logger.info('User created successfully', { userId: result.id });
      return result;
    } catch (error) {
      this.logger.error('Failed to create user', error, { email: userData.email });
      throw error;
    } finally {
      timer();
    }
  }
}

Error Handling

try {
  await riskyOperation();
} catch (error) {
  logger.error('Operation failed', error, {
    operation: 'riskyOperation',
    context: { /* relevant context */ }
  });
  
  // Re-throw if needed
  throw error;
}

API Reference

Logger Methods

• debug(message, context?) - Debug level logging
• info(message, context?) - Info level logging
• warn(message, context?) - Warning level logging
• error(message, error?, context?) - Error level logging
• fatal(message, error?, context?) - Fatal level logging
• logApiRequest(method, url, options?) - API request logging
• logApiResponse(method, url, status, responseTime, options?) - API response logging
• logApiError(method, url, error, options?) - API error logging
• startTimer(operation) - Performance timing
• setContext(key, value) - Set global context
• child(context) - Create child logger

Interceptors

• FetchInterceptor - Automatic Fetch API capture
• AxiosInterceptor - Automatic Axios capture
• XHRInterceptor - Automatic XMLHttpRequest capture

Utilities

• maskSensitiveData(data, options) - Sensitive data masking
• maskEmail(email) - Email masking
• maskCreditCard(cardNumber) - Credit card masking
• maskUrlParameters(url, sensitiveParams) - URL parameter masking

TypeScript Support

This library is written in TypeScript and provides full type definitions. All methods are properly typed with generics and interfaces to ensure type safety in your applications.

// Fully typed logger configuration
const config: LoggerConfig = {
  level: LogLevel.INFO,
  enableConsole: true,
  enableFile: true,
  filePath: './logs/app.log'
};

// Type-safe context
interface UserContext {
  userId: string;
  sessionId: string;
  ip: string;
}

const userLogger = logger.child<UserContext>({
  userId: '123',
  sessionId: 'sess-456',
  ip: '192.168.1.1'
});

Examples

Check out the examples/ directory for comprehensive usage examples:

• basic-usage.ts - Basic logging patterns
• advanced-usage.ts - Advanced features and configurations

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Add tests for your changes
4. Update documentation
5. Submit a pull request

License

MIT License - see the LICENSE file for details.

Support

• GitHub Issues: Report bugs or request features
• Documentation: Full API documentation

Changelog

v1.1.8

• Enhanced middleware system
• Improved sensitive data masking
• Performance optimizations
• Async middleware support
• New formatter options

v1.0.0

• Initial release
• Full TypeScript support
• API logging with interceptors
• Performance monitoring
• Sensitive data masking
• Multiple output writers
• Flexible formatting options