d-logger/README.md

# logger [![JSR](https://jsr.io/badges/@iankulin/logger)](https://jsr.io/@iankulin/logger) [![JSR Score](https://jsr.io/badges/@iankulin/logger/score)](https://jsr.io/@iankulin/logger/score)

> Flexible console logging utility with colors, and multiple output formats

## Features

- **Multiple log levels**: silent, error, warn, info, debug
- **Flexible output formats**: JSON or simple text
- **Caller detection**: Automatically identifies source file and line number based on log level
- **Color support**: Automatic TTY detection with colored output

## Install

Install with [JSR](https://jsr.io/@iankulin/logger) for Deno:

```sh
# Add to your deno.json
$ deno add @iankulin/logger

# Or import directly
$ deno run --allow-env --allow-sys your-script.js
```

## Quick Start

```typescript
import Logger from "@iankulin/logger";

const logger = new Logger();
logger.info('Hello from logger');
logger.error('Something went wrong');
```

## Usage Examples

### Basic Logging

```typescript
import Logger from "@iankulin/logger";
const logger = new Logger({ level: 'info' });

logger.error('Critical error occurred');
logger.warn('This is a warning');
logger.info('Informational message');
logger.debug('Debug info'); // Won't be shown (level is 'info')
```

### Log Levels

The logger supports five log levels (from least to most verbose):

- `silent` - Suppresses all output
- `error` - Only error messages
- `warn` - Error and warning messages
- `info` - Error, warning, and info messages (default)
- `debug` - All messages

```typescript
const logger = new Logger({ level: 'debug' });

// All of these will be logged
logger.error('Error message');
logger.warn('Warning message');
logger.info('Info message');
logger.debug('Debug message');

// Change level dynamically
logger.level('error');
logger.info('This will not be logged');

// Get current level
console.log(logger.level()); // 'error'
```

### Output Formats

#### JSON Format (Default)

```typescript
const logger = new Logger({ format: 'json' });
logger.info('Hello world');
```

```json
{
  "level": "info",
  "levelNumber": 2,
  "time": "2025-06-02T12:00:00.000Z",
  "pid": 12345,
  "hostname": "my-computer",
  "msg": "Hello world",
  "callerFile": "file:///path/to/file.js",
  "callerLine": 3
}
```

#### Simple Format

```typescript
const logger = new Logger({ format: 'simple' });
logger.error('Something failed');
```

```
[2025-07-04 22:50] [ERROR] [basic.js:3] Something failed
```

### Message Formatting

The logger supports `util.format()` style message formatting with placeholders like `%s`, `%d`, `%j`.

```typescript
const logger = new Logger({ format: 'json' });

// String formatting
logger.info('User %s has %d points', 'john', 100);
// Output: {"level":"info","msg":"User john has 100 points",...}

// JSON formatting
logger.info('Config: %j', { debug: true, port: 3000 });
// Output: {"level":"info","msg":"Config: {\"debug\":true,\"port\":3000}",...}

// Simple format example
const simpleLogger = new Logger({ format: 'simple' });
simpleLogger.warn('Processing file %s (%d bytes)', 'data.txt', 1024);
// Output: [2025-07-05 10:30] [WARN ] [app.js:15] Processing file data.txt (1024 bytes)
```

### Custom Colors

```typescript
const logger = new Logger({
  colours: {
    error: '\x1b[31m', // Red
    warn: '\x1b[93m', // Bright yellow
    info: '\x1b[36m', // Cyan
    debug: '\x1b[90m', // Dark gray
  },
});
```

### Caller Level Control

Control when caller information (file and line number) is included in log messages. This is useful for performance optimization since caller detection can be expensive.

```typescript
// Default: only include caller info for warnings and errors
const logger = new Logger({ callerLevel: 'warn' });

logger.error('Critical error'); // Includes caller info
logger.warn('Warning message'); // Includes caller info
logger.info('Info message'); // No caller info
logger.debug('Debug message'); // No caller info
```

**JSON Format Output:**

```json
{"level":"error","msg":"Critical error","callerFile":"/path/to/file.js","callerLine":42}
{"level":"info","msg":"Info message"}
```

**Simple Format Output:**

```
[2025-07-04 13:13] [ERROR] [app.js:42] Critical error
[2025-07-04 13:13] [INFO ] Info message
```

**Available callerLevel Options:**

- `'silent'` - Never include caller info (best performance)
- `'error'` - Only include caller info for errors
- `'warn'` - Include caller info for warnings and errors (default)
- `'info'` - Include caller info for info, warnings, and errors
- `'debug'` - Always include caller info

**Performance Tip:** For production applications that primarily log info/debug messages, setting `callerLevel: 'error'` can significantly improve performance by avoiding expensive stack trace analysis for routine logging.

## Constructor Options

| Option        | Type   | Default   | Description                                                                                     |
| ------------- | ------ | --------- | ----------------------------------------------------------------------------------------------- |
| `level`       | string | `'info'`  | Minimum log level to output (`'silent'`, `'error'`, `'warn'`, `'info'`, `'debug'`)              |
| `format`      | string | `'json'`  | Output format (`'json'` or `'simple'`)                                                          |
| `callerLevel` | string | `'warn'`  | Minimum log level to include caller info (`'silent'`, `'error'`, `'warn'`, `'info'`, `'debug'`) |
| `colours`     | object | See below | Color codes for each log level                                                                  |
| `levels`      | object | See below | Custom level names and numeric values                                                           |

## Common Usage Patterns

```typescript
import Logger from "@iankulin/logger";

// Production: JSON format with environment-based level
const prodLogger = new Logger({
  level: Deno.env.get('LOG_LEVEL') || 'info',
  format: 'json',
  callerLevel: 'error', // Performance optimization
});

// Development: Simple format with debug level
const devLogger = new Logger({
  level: 'debug',
  format: 'simple',
});

// Testing: Silent mode
const testLogger = new Logger({ level: 'silent' });
```

## Requirements

- Deno 1.37.0 or higher

## License

[MIT](LICENSE)

## Versions

- **1.0.0** - JSR release with full Deno support
  - Migrated from [npm version](https://www.npmjs.com/package/@iankulin/logger) to JSR (JavaScript Registry)
  - Full TypeScript support
  - Native Deno compatibility

## AI Disclosure

- AI Code tools were used in this project