🧰 smorg-utils

A lightweight, tree-shakable utility library with TypeScript support. Built with modern JavaScript standards, optimized for minimal bundle size and maximum performance.

✨ Features

• 🌳 Tree-shakable - Import only what you need
• 📦 Dual module support - Both ESM and CommonJS
• 🔷 TypeScript first - Full type safety and IntelliSense
• 🚀 Zero dependencies - No external dependencies
• 📱 Universal - Works in Node.js and browsers
• ⚡ High performance - Optimized for speed
• 🧪 Well tested - Comprehensive test coverage
• 🔌 Modular - Plugin-based architecture

📦 Installation

npm install smorg-utils

yarn add smorg-utils

pnpm add smorg-utils

🚀 Quick Start

1. Basic Usage (Zero Configuration)

import { logger } from 'smorg-utils';

logger.info('Hello, world!');
logger.error('Something went wrong', { error: 'details' });

2. Custom Logger

import { createLogger, LogLevel } from 'smorg-utils';

const appLogger = createLogger({
  level: LogLevel.DEBUG,
  name: 'MyApp'
});

appLogger.debug('Debugging info');
appLogger.info('Application started');

3. Production Configuration

import { createLogger, LogLevel, jsonFormatter } from 'smorg-utils/logger';
import { createRotatingFileTransport } from 'smorg-utils/logger/transports';

const productionLogger = createLogger({
  level: LogLevel.WARN,
  formatter: jsonFormatter,
  transport: createRotatingFileTransport({
    filename: 'app',
    dirname: './logs',
    dateRotation: true,
    maxFiles: 30,
    compress: true
  })
});

📚 Comprehensive Examples

New! We've created extensive real-world examples in the src/logger/examples/ directory:

• 01-basic-usage.ts - Start here! Zero-config to simple setups
• 02-formatters-examples.ts - Custom formatting and output styles
• 03-transports-examples.ts - File logging, rotation, custom destinations
• 04-middleware-examples.ts - Express.js integration patterns
• 05-advanced-examples.ts - Production patterns, performance, testing

Each example is fully documented with real-world scenarios and can be run with:

npx ts-node src/logger/examples/01-basic-usage.ts

📚 API Documentation

Core Logger

A high-performance, configurable logging utility.

Basic Example

import { Logger, LogLevel, simpleFormatter } from 'smorg-utils';

const logger = new Logger({
  level: LogLevel.INFO,
  formatter: simpleFormatter,
  context: { service: 'api' }
});

logger.info('Server started', { port: 3000 });
// Output: [2023-12-07T10:30:00.000Z] INFO  Server started {"service":"api","port":3000}

Configuration Options

interface LoggerConfig {
  level?: LogLevel | LogLevelName;          // Minimum log level
  formatter?: LogFormatter;                 // Custom formatter function
  transport?: LogTransport;                 // Custom transport function
  includeTimestamp?: boolean;               // Include timestamps (default: true)
  context?: Record<string, unknown>;        // Global context
  name?: string;                           // Logger name
}

Log Levels

enum LogLevel {
  DEBUG = 0,
  INFO = 1,
  WARN = 2,
  ERROR = 3,
  SILENT = 4
}

Express Integration

For Express.js applications, import the HTTP middleware utilities:

import { createLogger, createHttpLogger, simpleFormatter } from 'smorg-utils';

const logger = createLogger({
  formatter: simpleFormatter,
  context: { service: 'api' }
});

// Create HTTP middleware for request/response logging
const httpLogger = createHttpLogger(logger, {
  includeFields: {
    method: true,
    url: true,
    ip: true,
    userAgent: false,
  },
  statusCodeLevels: {
    success: 'info',
    clientError: 'warn', 
    serverError: 'error',
  },
  skip: (req, res) => req.url === '/health'
});

// Add to Express app
app.use(httpLogger.requestLogger);
app.use(httpLogger.errorLogger);

File Logging with Rotation

For production applications needing file logging:

import { createLogger, createRotatingFileTransport } from 'smorg-utils';

const logger = createLogger({
  transport: createRotatingFileTransport({
    filename: 'app',
    dirname: './logs',
    dateRotation: true,     // Daily rotation
    maxFiles: 30,          // Keep 30 days
    compress: true,        // Compress old logs
    maxSize: 10 * 1024 * 1024  // 10MB max size
  })
});

// Separate files by log level
import { createMultiLevelFileTransport } from 'smorg-utils';

const multiLogger = createLogger({
  transport: createMultiLevelFileTransport({
    filename: 'app',
    dirname: './logs/by-level'
  })
});

Advanced Production Setup

import {
  createLogger,
  createHttpLogger,
  createRotatingFileTransport,
  LogLevel,
  simpleFormatter
} from 'smorg-utils';

const isProduction = process.env.NODE_ENV === 'production';

// Multi-transport logger
const logger = createLogger({
  level: isProduction ? LogLevel.INFO : LogLevel.DEBUG,
  transport: (message, level) => {
    // Console in development
    if (!isProduction) {
      console.log(simpleFormatter(level, message, new Date()));
    }
    
    // Always log to rotating files
    const fileTransport = createRotatingFileTransport({
      filename: 'app',
      dirname: './logs',
      dateRotation: true,
      maxFiles: 30,
      compress: true
    });
    
    fileTransport(message, level);
  },
  context: { 
    service: 'api',
    instance: process.env.INSTANCE_ID,
    version: process.env.APP_VERSION
  }
});

// Production-ready HTTP logging
const httpLogger = createHttpLogger(logger, {
  includeFields: {
    method: true,
    url: true,
    ip: true,
    userAgent: isProduction,
    headers: !isProduction
  },
  skip: (req, res) => {
    return isProduction && (
      req.url.startsWith('/health') ||
      req.url.startsWith('/static')
    );
  }
});

app.use(httpLogger.requestLogger);
app.use(httpLogger.errorLogger);

Factory Functions

createLogger(config?: LoggerConfig): ILogger

Creates a new logger instance with optional configuration.

import { createLogger, LogLevel } from 'smorg-utils';

const logger = createLogger({
  level: LogLevel.WARN,
  name: 'MyService'
});

createNoopLogger(): ILogger

Creates a logger that discards all messages (useful for testing).

import { createNoopLogger } from 'smorg-utils';

const logger = createNoopLogger();
logger.info('This will not be logged');

Child Loggers

Create child loggers with inherited context:

import { createLogger } from 'smorg-utils';

const parentLogger = createLogger({
  context: { service: 'api', version: '1.0.0' }
});

const requestLogger = parentLogger.child({ 
  requestId: 'req-123',
  userId: 'user-456' 
});

requestLogger.info('Processing request');
// Includes context from both parent and child

🆚 Migration from Monolithic Loggers

If you're migrating from a feature-rich logger that includes everything built-in:

Before (Monolithic Logger)

import Logger from './logger';  // 20-30KB bundle

app.use(Logger.requestLogger);
app.use(Logger.errorLogger);

After (Our Modular Approach)

// Import only what you need (~8-12KB total)
import { 
  createLogger, 
  createHttpLogger,
  createRotatingFileTransport 
} from 'smorg-utils';

const logger = createLogger({
  transport: createRotatingFileTransport({
    filename: 'app',
    dirname: './logs',
    dateRotation: true
  })
});

const httpLogger = createHttpLogger(logger);
app.use(httpLogger.requestLogger);
app.use(httpLogger.errorLogger);

🏗️ Build Configuration

This package supports multiple module formats:

ESM (Recommended)

import { Logger } from 'smorg-utils';

CommonJS

const { Logger } = require('smorg-utils');

Deep Imports (Tree-shaking)

// Import specific utilities only
import { createLogger } from 'smorg-utils/logger';
import { createHttpLogger } from 'smorg-utils/middlewares/express-logger';

📊 Bundle Size

This package is optimized for minimal bundle size:

| Import Pattern | Bundle Size | Features | |---------------|-------------|----------| | Core logger only | ~4KB | Basic logging | | + Express middleware | ~8KB | HTTP request/response logging | | + File transports | ~12KB | File logging with rotation | | Full package | ~15KB | All features |

Compare this to monolithic loggers that often bundle 20-30KB+ regardless of usage.

🧪 Testing

The package includes comprehensive tests and utilities for testing:

import { createNoopLogger } from 'smorg-utils';

// Use in tests to suppress log output
const logger = createNoopLogger();

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and ensure:

1. All tests pass (npm test)
2. Code is properly formatted (npm run format)
3. No linting errors (npm run lint)
4. TypeScript compiles without errors (npm run type-check)

📄 License

MIT © [Your Name]

🔄 Changelog

1.0.0

• Initial release
• Core logger with full TypeScript support
• Express middleware utilities
• File transport with rotation
• Tree-shaking support
• Dual module format (ESM/CJS)
• Comprehensive test coverage