@untools/logger/README.md

An enhanced logger for JavaScript/TypeScript that handles DOM elements and circular references

# @untools/logger

An enhanced, context-aware logger for JavaScript/TypeScript designed for **Wide Events** and **Canonical Log Lines**. It features premium aesthetics for both Node.js and Browser environments, handles DOM elements, and safely manages circular references.

Inspired by [Logging Sucks](https://loggingsucks.com) and the philosophy of observability wide events.

## Features

- 🚀 **Wide Events**: Consolidation of request context into single, rich log lines.
- 🔗 **Context Accumulation**: Persistent metadata that follows your execution flow.
- 👶 **Child Loggers**: Easily create request-scoped loggers with inherited context.
- 🎨 **Premium Aesthetics**: High-contrast dark theme for Terminal; modern, clean CSS for Browser.
- 🧩 **DOM Support**: Specialized formatting for DOM elements (Browser only).
- 🔄 **Circular Safety**: Robust handling of circular references in objects.
- 🛠 **Environment Aware**: Automatic inclusion of `_ts`, `_env`, and `_pid` metadata.

## Best Practices

This logger is built to support **Wide Events** (Canonical Log Lines). Instead of scattering log lines throughout your handler, accumulate context and emit a single structured event at completion.

### 1. Initialize Context
Start a "service hop" by creating a child logger with request context.

```typescript
import { logger } from '@untools/logger';

const requestLogger = logger.child({
  _rid: 'req_a7b2...', // Request ID
  userId: 'user_123',
  path: '/api/checkout'
});
```

### 2. Accumulate Business Context
Add context as it becomes available during process execution.

```typescript
requestLogger.addContext({
  cart_value: 2499,
  item_count: 3,
  subscription: 'premium'
});
```

### 3. Emit at Completion
Use a `finally` block or completion handler to emit the final wide event.

```typescript
try {
  // ... business logic
  requestLogger.info({ outcome: 'success', status_code: 200 });
} catch (error) {
  requestLogger.error({ outcome: 'error', error: error.message });
}
```

## Usage

### Server (Node.js)
The server output uses premium ANSI color coding and bold keys for high readability in dark terminals.

```typescript
logger.info("Server started", { port: 3000 });
```

### Browser
In the browser, logs are beautifully styled with CSS and include collapsed groups for raw object inspection.

```typescript
logger.debug("Component mounted", { props, state });
```

### Log Levels
Default level is `INFO` (2). Change it via:

```typescript
import { LogLevel } from '@untools/logger';
logger.setLogLevel(LogLevel.DEBUG); // 3
```

## Credits & References

Special thanks to **Boris Tane** ([@boristane](https://github.com/boristane)) for the foundational concepts of Wide Events and Canonical Log Lines.

Key References:
- [Logging Sucks](https://loggingsucks.com)
- [Observability Wide Events 101](https://boristane.com/blog/observability-wide-events-101/) by Boris Tane
- [Stripe - Canonical Log Lines](https://stripe.com/blog/canonical-log-lines)

## License

MIT