npm package: @midtownhi/logger
Description: A NestJS-style configurable TypeScript logger with colored output and log levels.
Latest version: 2.0.2

# @midtownhi/logger

A NestJS-style configurable TypeScript logger with colored output and log levels.

## Installation

```bash
npm install @midtownhi/logger
```

## Features

- Multiple log levels: ERROR, WARN, LOG, DEBUG, VERBOSE
- NestJS-compatible API with both static and instance methods
- Colored output for better readability
- Contextual logging with global and per-instance contexts
- Timestamp support
- Environment-aware behavior with production safeguards
- Global log level control

## Usage

### Static Usage (NestJS-style)

```typescript
import { Logger, LogLevel } from '@midtownhi/logger';

// Use static methods (similar to NestJS)
Logger.log('This is a regular log message');
Logger.error('Something went wrong!', 'Optional stack trace');
Logger.warn('This is a warning');
Logger.debug('Debug information');
Logger.verbose('Very detailed information');

// With context
Logger.log('Message with context', 'ContextName');

// Set global context for all static calls
Logger.setGlobalContext('AppName');
Logger.log('Will use AppName context');
```

### Instance Usage

```typescript
import { Logger, LogLevel } from '@midtownhi/logger';

// Create a logger with a context
const logger = new Logger('MyComponent');

// Log at different levels
logger.log('This is a regular log message');
logger.error('Something went wrong!', 'Optional stack trace');
logger.warn('This is a warning');
logger.debug('Debug information');
logger.verbose('Very detailed information');

// Change context at runtime
logger.setContext('NewContext');

// Create a contextual logger
const authLogger = Logger.getInstance('Auth');
const dbLogger = Logger.getInstance('Database');
```

### Log Level Control

```typescript
import { Logger, LogLevel } from '@midtownhi/logger';

// Set global log level (affects all loggers)
Logger.setLogLevel(LogLevel.WARN);

// Set per-instance log level (only works in development)
const logger = new Logger('MyComponent');
logger.setLogLevel(LogLevel.DEBUG);

// In production, all loggers use the global log level regardless of settings
```

## Production Mode Behavior

In production (`process.env.NODE_ENV === 'production'`):

- The global log level defaults to `LogLevel.LOG`
- All logger instances use the global log level, regardless of instance settings
- Attempts to override log levels are ignored
- This ensures consistent, controlled logging in production environments

In development:

- The global log level defaults to `LogLevel.DEBUG`
- Logger instances can have custom log levels
- Per-call log level overrides work normally

## Log Levels

- `ERROR`: Only critical errors
- `WARN`: Errors and warnings
- `LOG`: Errors, warnings, and regular logs (default in production)
- `DEBUG`: Everything above plus debug messages (default in development)
- `VERBOSE`: All messages, including the most detailed ones

## API

### Static Methods

- `Logger.log(message, context?)`: Regular log messages
- `Logger.error(message, trace?, context?)`: Error messages with optional stack trace
- `Logger.warn(message, context?)`: Warning messages
- `Logger.debug(message, context?)`: Debug information
- `Logger.verbose(message, context?)`: Very detailed information
- `Logger.getInstance(context?)`: Get or create a logger instance with context
- `Logger.setLogLevel(level)`: Set the global log level for all loggers
- `Logger.setGlobalContext(context)`: Set global context for static methods

### Constructor

#### `new Logger(context?, options?)`

Creates a new logger instance.

- `context` (optional): A string context name to include in log messages
- `options` (optional): Configuration options object

##### Options

- `timestamp` (boolean): Whether to include timestamps (default: `true`)
- `level` (LogLevel): Instance log level (ignored in production)

### Instance Methods

- `log(message, context?)`: Regular log messages
- `error(message, trace?, context?)`: Error messages, with optional stack trace
- `warn(message, context?)`: Warning messages
- `debug(message, context?)`: Debug information
- `verbose(message, context?)`: Very detailed information
- `setLogLevel(level)`: Change this instance's log level (no effect in production)
- `setContext(context)`: Change this instance's context
- `createLoggerWithContext(context)`: Create a new logger with specified context

## Implementing Custom Loggers

The library exports a `LoggerService` interface that can be implemented for custom logging solutions:

```typescript
export interface LoggerService {
    log(message: any, context?: string): void;
    error(message: any, trace?: string, context?: string): void;
    warn(message: any, context?: string): void;
    debug(message: any, context?: string): void;
    verbose(message: any, context?: string): void;
    setContext(context: string): void;
    setLogLevel(level: LogLevel): void;
}
```

## License

MIT