npm package: @loggerhub/winston
Description: Winston adapter for LoggerHub
Author: OneTeamSoftware
Latest version: 1.0.2

# @loggerhub/winston

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

## Installation

```bash
npm install @loggerhub/winston @loggerhub/core
```

## Usage

### Basic Usage with Factory

```typescript
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

```bash
# .env
LOGGER_ADAPTER=winston
LOGGER_LEVEL=debug
```

```typescript
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

```typescript
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:

```typescript
// 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:

```typescript
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:

```typescript
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:

```bash
# 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