npm package: @fimbul-works/logger
Description: A lightweight, TypeScript-friendly wrapper around Pino that provides flexible logging patterns with automatic argument handling
Author: FimbulWorks
Latest version: 1.0.1

# @fimbul-works/logger

A lightweight, TypeScript-friendly wrapper around [Pino](https://getpino.io/) that provides flexible logging patterns with automatic argument handling.

[![npm version](https://badge.fury.io/js/%40logger-works%2Flogger.svg)](https://www.npmjs.com/package/@logger-works/logger)
[![TypeScript](https://badges.frapsoft.com/typescript/code/typescript.svg?v=101)](https://github.com/microsoft/TypeScript)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@logger-works/logger)](https://bundlephobia.com/package/@logger-works/logger)

**Note:** This is a wrapper around [Pino](https://getpino.io/). For advanced configuration and features, refer to the [Pino documentation](https://getpino.io/#/docs/api).

## Quick Start

```typescript
import Logger from 'your-package-name';

const logger = new Logger();

logger.info('Hello, world!');
logger.error('I AM ERROR');
```

## Installation

```bash
npm install @logger-works/logger
```

## Features

- 🔄 Multiple argument patterns supported (console-style, Pino-style, printf-style)
- 🎯 TypeScript support with full type definitions
- 🧪 Automatic test environment detection (disables output in `NODE_ENV=test`)
- 🚀 Zero-config defaults with STDOUT/STDERR separation
- 📦 Access to underlying Pino instance for advanced usage

## Usage Patterns

The logger intelligently handles different argument patterns to accommodate various logging styles:

### 1. Simple String Message

```typescript
logger.info('Server started on port 3000');
// Output: {"level":30,"time":1234567890,"msg":"Server started on port 3000"}
```

### 2. Pino-Style (Object First)

Standard Pino pattern with structured data first, message second:

```typescript
logger.info({ userId: 123, action: 'login' }, 'User logged in');
// Output: {"level":30,"time":1234567890,"userId":123,"action":"login","msg":"User logged in"}
```

### 3. Console-Style (Message First, Object Second)

Automatically swaps arguments to Pino format:

```typescript
logger.info('User logged in', { userId: 123, action: 'login' });
// Output: {"level":30,"time":1234567890,"userId":123,"action":"login","msg":"User logged in"}
```

### 4. Printf-Style Formatting

Uses Pino's built-in printf formatting when `%` is detected:

```typescript
logger.info('User %s logged in from %s', 'john', '192.168.1.1');
// Output: {"level":30,"time":1234567890,"msg":"User john logged in from 192.168.1.1"}
```

### 5. Message with Multiple Arguments

Wraps additional arguments in a structured `args` field:

```typescript
logger.info('Processing items', 'item1', 'item2', 'item3');
// Output: {"level":30,"time":1234567890,"args":["item1","item2","item3"],"msg":"Processing items"}
```

### 6. Primitive Values

Non-string primitives are wrapped in an `args` array:

```typescript
logger.info(42, true, null);
// Output: {"level":30,"time":1234567890,"args":[42,true,null],"msg":"Log event"}
```

## API

All methods support the argument patterns described above:

- `logger.info(...args)` - Info level logs
- `logger.error(...args)` - Error level logs
- `logger.warn(...args)` - Warning level logs
- `logger.debug(...args)` - Debug level logs
- `logger.log(level, ...args)` - Log at specified level

### Access Raw Pino Instance

For advanced Pino features:

```typescript
const pinoInstance = logger.getRawLogger();
pinoInstance.child({ requestId: '123' });
```

## Default Behavior

### Output Destinations

By default, the logger sends:
- **Info, warn, debug** logs → STDOUT (file descriptor 1)
- **Error** logs → STDERR (file descriptor 2)

### Test Environment

When `NODE_ENV=test`, all output is automatically disabled to keep test output clean.

### Custom Targets

Override default targets with your own configuration:

```typescript
const logger = new Logger({
  transport: {
    targets: [
      {
        target: 'pino-pretty',
        options: { colorize: true }
      }
    ]
  }
});
```

## License

MIT License - See [LICENSE](LICENSE) file for details.

---

Built with ⚡ by [loggerWorks](https://github.com/logger-works)