@loggerhub/winston

Winston adapter for LoggerHub - A TypeScript logging library that provides Winston integration through the LoggerHub core interface.

Installation

npm install @loggerhub/winston @loggerhub/core

Usage

Basic Usage with Factory

import { LoggerFactory } from '@loggerhub/core';

// Winston adapter is auto-registered when imported
import '@loggerhub/winston';

const factory = new LoggerFactory();
const logger = factory.createLogger({
    LOGGER_ADAPTER: 'winston',
    LOGGER_LEVEL: 'info'
});

// Use the logger
await logger.info('Application started');
await logger.debug('Debug information', { userId: 123 });
await logger.warning('This is a warning');
await logger.error('An error occurred', new Error('Something went wrong'));
await logger.critical('Critical system error');

Environment Configuration

# .env
LOGGER_ADAPTER=winston
LOGGER_LEVEL=debug

import { LoggerFactory } from '@loggerhub/core';
import '@loggerhub/winston'; // Auto-registers Winston adapter

const factory = new LoggerFactory();
const logger = factory.createLogger(); // Uses environment variables

await logger.info('Using Winston via environment config');

Direct Usage

import { WinstonLogger } from '@loggerhub/winston';

const logger = new WinstonLogger({ 
  LOGGER_ADAPTER: 'winston', 
  LOGGER_LEVEL: 'debug',
  // Any Winston-specific options
});

await logger.info('Hello World!');

API

WinstonLoggerFactory

Implements LoggerFactoryInterface from @loggerhub/core.

Methods

• createLogger(config: TypeLoggerConfig): LoggerInterface - Creates a new Winston logger instance

WinstonLogger

Implements LoggerInterface from @loggerhub/core.

Methods

All methods are async and return Promise<void>:

• log(level: string, ...args: unknown[]): Promise<void> - Log with specified level
• debug(...args: unknown[]): Promise<void> - Log debug message
• info(...args: unknown[]): Promise<void> - Log info message
• warning(...args: unknown[]): Promise<void> - Log warning message
• error(...args: unknown[]): Promise<void> - Log error message
• critical(...args: unknown[]): Promise<void> - Log critical message

Flexible Argument Patterns

All logging methods support multiple argument patterns:

// Simple message
await logger.info('Simple message');

// Object only
await logger.info({ key: 'value' });

// Message with metadata
await logger.info('User action', { userId: 123, action: 'login' });

// Multiple arguments
await logger.info('Operation completed:', { status: 'success' }, 'Additional info');

// Mixed types
await logger.error('Error occurred:', new Error('Connection failed'), { retryCount: 3 });

Configuration

The Winston logger accepts standard LoggerHub configuration:

interface TypeLoggerConfig {
  LOGGER_ADAPTER?: string;      // 'winston' for this adapter
  LOGGER_LEVEL?: EnumLogLevel;  // debug, info, warning, error, critical
  [key: string]: unknown;       // Additional Winston-specific options
}

Example with Winston-specific options:

const logger = factory.createLogger({
  LOGGER_ADAPTER: 'winston',
  LOGGER_LEVEL: 'info',
  // Winston-specific options
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});

Testing

Run the test suite:

# Run all tests
npm test

# Run with coverage
npm run test:coverage

Test Structure

tests/
├── unit/
│   ├── WinstonLoggerFactory.test.ts    # Factory tests
│   ├── WinstonLogger.test.ts           # Logger implementation tests
│   └── contract-compliance.test.ts     # Interface compliance tests
├── integration/
│   └── winston-integration.test.ts     # Integration with core tests
└── index.test.ts                       # Test suite entry point

Test Coverage

The test suite covers:

• ✅ Factory creation and configuration
• ✅ All logging methods (debug, info, warning, error, critical)
• ✅ Interface compliance with LoggerInterface and LoggerFactoryInterface
• ✅ Flexible argument patterns
• ✅ Async method behavior
• ✅ Integration with core registry
• ✅ Error handling
• ✅ Concurrent logging operations
• ✅ Type safety verification

Dependencies

• @loggerhub/core - Core logging interfaces and utilities
• winston - The Winston logging library

License

MIT

Contributing

1. Ensure all tests pass: npm test
2. Maintain test coverage above 90%
3. Follow the existing code style
4. Update documentation for API changes