npm package: @nodifier/loguru
Description: Utils for logging
Author: gamemasterdev
Latest version: 1.0.1


# @nodifier/loguru

A simple and flexible logging utility for Node.js, inspired by Python's loguru. Provides easy-to-use logging with support for multiple transports (console, file), custom formatting, log levels, and context.

## Features
- Simple API for logging at different levels (`info`, `warn`, `error`, `debug`, `fatal`)
- Pluggable transports (console, file, custom)
- Customizable log formats (JSON, plain text, etc.)
- Context support via child loggers
- TypeScript support

## Installation

```bash
npm install @nodifier/loguru
```

## Basic Usage (Singleton Logger)

```typescript
import { logger } from '@nodifier/loguru';

logger.info('Hello, world!');
logger.warn('This is a warning');
logger.error('Something went wrong', { error: new Error('Oops') });
logger.debug('Debugging info', { data: { foo: 'bar' } });
```

## Creating a Custom Logger Instance

```typescript
import { Logger, ConsoleTransport } from '@nodifier/loguru';

const logger = new Logger({
  level: 'DEBUG',
  serviceName: 'MyService',
  transports: [new ConsoleTransport()],
});

logger.info('Custom logger instance!');
```

## Using File Transport

```typescript
import { Logger, FileTransport } from '@nodifier/loguru';

const logger = new Logger({
  level: 'INFO',
  serviceName: 'FileService',
  transports: [
    new FileTransport({ path: './logs/app.log', maxSize: 1024 * 1024 }),
  ],
});

logger.info('This will be written to app.log');
```

## Using JSON Formatting

```typescript
import { Logger, ConsoleTransport, JsonFormatter } from '@nodifier/loguru';

const logger = new Logger({
  level: 'INFO',
  serviceName: 'JsonService',
  transports: [new ConsoleTransport()],
  // The formatter is used internally by transports, but you can customize output in your own transport
});

// To format manually:
import { JsonFormatter } from '@nodifier/loguru';
const formatter = new JsonFormatter();
const formatted = formatter.format({
  timestamp: new Date().toISOString(),
  level: 'INFO',
  service: 'JsonService',
  message: 'Log as JSON',
});
console.log(formatted);
```

## Adding Context with Child Loggers

```typescript
import { logger } from '@nodifier/loguru';

const userLogger = logger.child({ userId: '1234' });
userLogger.info('User-specific log');
```

## API Reference

- `Logger(config: LoggerConfig)`: Create a new logger instance.
  - `config.level`: Minimum log level (`DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`)
  - `config.serviceName`: Name of the service/application
  - `config.transports`: Array of transports (e.g., `ConsoleTransport`, `FileTransport`)
  - `config.defaultMeta`: Default metadata to include with every log
  - `config.customLevels`: Custom log levels (optional)
- `logger.info(message, meta?)`: Log an info message
- `logger.warn(message, meta?)`: Log a warning
- `logger.error(message, meta?)`: Log an error
- `logger.debug(message, meta?)`: Log a debug message
- `logger.fatal(message, meta?)`: Log a fatal error
- `logger.child(meta)`: Create a child logger with additional context

### Transports
- `ConsoleTransport(level?)`: Log to the console (stdout)
- `FileTransport({ path, maxSize? }, level?)`: Log to a file with optional rotation

### Formatter
- `JsonFormatter`: Formats log entries as JSON strings

## License

MIT