# better-logger

**console.log is broken. better.log fixes it.**

<p align="center">
  <!-- Workflow Status -->
  <a href="https://github.com/0xmilord/better-logger/actions/workflows/better-logger-ci.yml">
    <img src="https://github.com/0xmilord/better-logger/actions/workflows/better-logger-ci.yml/badge.svg" alt="CI Status">
  </a>
  <a href="https://github.com/0xmilord/better-logger/actions/workflows/bundle-size.yml">
    <img src="https://github.com/0xmilord/better-logger/actions/workflows/bundle-size.yml/badge.svg" alt="Bundle Size">
  </a>

  <!-- Package Info -->
  <a href="https://www.npmjs.com/package/@better-logger/core">
    <img src="https://img.shields.io/npm/v/@better-logger/core?color=0366d6&label=version" alt="npm version">
  </a>
  <a href="https://www.npmjs.com/package/@better-logger/core">
    <img src="https://img.shields.io/npm/dw/@better-logger/core?color=0366d6" alt="npm downloads">
  </a>
  <a href="https://www.npmjs.com/package/@better-logger/core">
    <img src="https://img.shields.io/bundlephobia/minzip/@better-logger/core?color=0366d6&label=gzip" alt="Bundle Size">
  </a>

  <!-- Code Quality -->
  <a href="https://github.com/0xmilord/better-logger/blob/main/LICENSE">
    <img src="https://img.shields.io/npm/l/@better-logger/core?color=0366d6" alt="License">
  </a>
  <a href="https://github.com/0xmilord/better-logger">
    <img src="https://img.shields.io/github/last-commit/0xmilord/better-logger?color=0366d6" alt="Last Commit">
  </a>
  <a href="https://github.com/0xmilord/better-logger/issues">
    <img src="https://img.shields.io/github/issues/0xmilord/better-logger?color=0366d6" alt="Issues">
  </a>
  <a href="https://github.com/0xmilord/better-logger/pulls">
    <img src="https://img.shields.io/github/issues-pr/0xmilord/better-logger?color=0366d6" alt="Pull Requests">
  </a>

  <!-- Ecosystem -->
  <a href="https://marketplace.visualstudio.com/items?itemName=0xmilord.better-logger">
    <img src="https://img.shields.io/badge/vscode-extension-0366d6" alt="VS Code Extension">
  </a>
  <a href="https://0xmilord.github.io/better-logger/">
    <img src="https://img.shields.io/badge/docs-site-0366d6" alt="Documentation">
  </a>
</p>

<p align="center">
  <strong>Zero Dependencies · 3.8KB Gzipped · 280 Tests · 96% Coverage · 8 Framework Integrations</strong>
</p>

---

You wouldn't debug a multi-step process with sticky notes.
Stop debugging your app with console.log.

```bash
npm install @better-logger/core
```

## The Problem

```typescript
// console.log — flat noise, no structure
console.log('start')
console.log('user', user)
console.log('after db')
console.log('payment', payment)
console.log('done')
```

And then trying to mentally reconstruct:
- What ran first?
- How long did each thing take?
- Where did it fail?
- What were the values at each step?

## The Solution

```typescript
import { better } from '@better-logger/core'

// Same code. Better output.
better.log('start')
better.log('user', user)
better.log('after db')
better.log('payment', payment)
better.log('done')
```

**What you get:**

```
🚀 [flow:default] (tid: abc123)
  → start
  ✓ start (12ms)
  → user
    data: { email: "test@example.com" }
  ✓ user (45ms)
  → after db
  ✓ after db (210ms)
  → payment
    data: { amount: 99.99 }
  ✓ payment (183ms)
  → done
  ✓ done (0ms)
🏁 [flow:default] success (450ms)
```

**Automatic timing. Context propagation. Hierarchical grouping. Zero config.**

## Why better.log?

| Feature | console.log | pino | winston | better.log |
|---------|-------------|------|---------|------------|
| Drop-in replacement | — | ❌ | ❌ | ✅ |
| Auto-flow grouping | ❌ | ❌ | ❌ | ✅ |
| Automatic timing | ❌ | Manual | Manual | ✅ |
| Context propagation | ❌ | Manual | Manual | ✅ |
| Hierarchical output | ❌ | ❌ | ❌ | ✅ |
| Zero dependencies | ✅ | ❌ | ❌ | ✅ |
| Bundle size | 0KB | 30KB | 100KB | **8KB** |
| TypeScript support | ❌ | ✅ | ✅ | ✅ |
| Browser support | ✅ | ❌ | ❌ | ✅ |
| Structured output | ❌ | ✅ | ✅ | ✅ |
| Auto-error tracking | ❌ | ❌ | ❌ | ✅ |

## Quick Start

### Replace console.log

```typescript
import { better } from '@better-logger/core'

// Before
console.log('User created:', user)
console.error('Payment failed:', error)

// After
better.log('User created:', user)
better.log.error('Payment failed:', error)
```

### Severity tagging

```typescript
better.log.info('Server started', { port: 3000 })
better.log.warn('Slow query', { duration: 250 })
better.log.error('Connection failed', error)
```

### When you need structure

```typescript
const flow = better.flow('checkout', { tags: ['payment'] })
flow.setContext({ userId: 'user-123' })

const step = flow.step('charge-card', { amount: 99.99 })
const result = await paymentGateway.charge({ amount: 99.99 })
step.success(result)

flow.success()
```

### Async helper

```typescript
const flow = better.flow('data-export')

const data = await flow.run('fetch-data', async () => {
  return await db.users.find({})
})

flow.success()
```

## API Reference

### Core (90% of users need only this)

```typescript
better.log('message')              // Simple message
better.log('message', data)        // Message with data
better.log.warn('warning', data)   // Warning (auto-tags flow)
better.log.error('error', error)   // Error (fails flow)

better.flow('name', options)       // Explicit flow
better.setEnabled(false)           // Disable all logging
better.subscribe(fn)               // Listen for flow completions
better.toJSON(flow)                // Export flow as JSON
```

### Transports (Production)

```typescript
better.log.toFile('app.log')                    // File transport
better.log.toStream(process.stdout)             // Stream transport
better.log.toHttp('https://api.example.com/log') // HTTP transport
```

### Production Features

```typescript
better.log.redact(['password', 'ssn'])          // PII redaction
better.log.async(true)                          // Non-blocking async
better.log.flush()                              // Force complete
```

### Configuration

```typescript
better.setIdleTimeout(200)                      // Auto-complete timeout
better.setFlowName('my-app')                    // Default flow name
better.setDefaultTags(['app', 'v3'])            // Tags on all flows
```

## Real-World Examples

We've included 11 comprehensive examples:

| Example | What it shows |
|---------|--------------|
| `examples/01-express-rest-api.js` | Express middleware, CRUD, error handling |
| `examples/02-background-job-processor.js` | Job queue, retry logic, nested flows |
| `examples/03-authentication-flow.js` | Login, token refresh, password reset |
| `examples/04-ecommerce-order-processing.js` | Multi-step checkout, payments, shipping |
| `examples/05-cli-tool.js` | CLI commands, progress, dry-run |
| `examples/06-api-integration-client.js` | HTTP client, retry, rate limiting |
| `examples/07-microservice-distributed-tracing.js` | Trace context, downstream calls |
| `examples/08-testing-utilities.js` | Test runner, assertions, perf tests |
| `examples/09-data-pipeline.js` | ETL stages, transforms, aggregation |
| `examples/10-full-application.js` | Complete Node.js app with all patterns |
| `examples/11-angular-app.js` | Angular service, HTTP interceptor, error handler |

Framework integrations (13 total):

| Package | Framework | Install | When to use this vs Core |
|---------|-----------|---------|--------------------------|
| `@better-logger/express` | Express.js | `npm i @better-logger/express` | **Auto-logging** for every request vs manual middleware. |
| `@better-logger/fastify` | Fastify | `npm i @better-logger/fastify` | **Plugin** with hooks vs manual `app.addHook`. |
| `@package/koa` | Koa | `npm i @better-logger/koa` | **Middleware** + error handler vs manual `ctx` logic. |
| `@better-logger/hono` | Hono (Edge) | `npm i @better-logger/hono` | **Edge-compatible** middleware for Cloudflare/Vercel. |
| `@better-logger/nestjs` | NestJS | `npm i @better-logger/nestjs` | **Module + Interceptor** + Exception filter integration. |
| `@better-logger/nextjs` | Next.js | `npm i @better-logger/nextjs` | **Plugin** for API routes and server components. |
| `@better-logger/react` | React | `npm i @better-logger/react` | **Hooks** for lifecycle and error boundaries. |
| `@better-logger/angular` | Angular | `npm i @better-logger/angular` | **Service** + HTTP interceptor + error handler. |
| `@better-logger/vue` | Vue 2/3 | `npm i @better-logger/vue` | **Plugin** + composable for lifecycle tracking. |
| `@better-logger/svelte` | Svelte | `npm i @better-logger/svelte` | **Function** for component and async tracking. |
| `@better-logger/sveltekit` | SvelteKit | `npm i @better-logger/sveltekit` | **Server hook** for routes and API endpoints. |
| `@better-logger/astro` | Astro | `npm i @better-logger/astro` | **Integration** for build and dev server logging. |
| `@better-logger/cli` | CLI Tools | `npm i @better-logger/cli` | **Helpers** for progress bars, tables, commands. |

## Performance

| Metric | better.log | console.log | pino | winston |
|--------|-----------|-------------|------|---------|
| Simple message | 89ms | 45ms | 38ms | 120ms |
| With data | 142ms | 78ms | 65ms | 180ms |
| Async mode | 52ms | — | — | — |
| Bundle size | **8KB** | 0KB | 30KB | 100KB |

**better.log is fast enough for 95% of use cases.** For high-throughput, use async mode.

See [BENCHMARKS.md](docs/BENCHMARKS.md) for full benchmarks.

## Migration

### From console.log

```bash
npx @better-logger/codemod .
```

Or manually: Replace `console.log` → `better.log`, `console.error` → `better.log.error`.

### From pino/winston

See [Migration Guides](docs/MIGRATE-FROM-PINO.md), [docs/MIGRATE-FROM-WINSTON.md](docs/MIGRATE-FROM-WINSTON.md).

## Package Health

| Metric | Value |
|--------|-------|
| **Tests** | 280 passing |
| **Coverage** | 96.61% |
| **Bundle size** | 10.73KB (3.8KB gzipped) |
| **Dependencies** | 0 |
| **TypeScript** | Full support |
| **Runtimes** | Node 18+, Browser, Edge |

## Ecosystem

| Package | Purpose |
|---------|---------|
| `@better-logger/core` | Core library |
| `packages/express/` | Express middleware |
| `packages/fastify/` | Fastify plugin |
| `packages/koa/` | Koa middleware |
| `packages/hono/` | Hono/Edge middleware |
| `packages/nestjs/` | NestJS module |
| `packages/nextjs/` | Next.js plugin |
| `packages/react/` | React hooks |
| `packages/angular/` | Angular service |
| `packages/vue/` | Vue 2/3 plugin |
| `packages/svelte/` | Svelte functions |
| `packages/sveltekit/` | SvelteKit hooks |
| `packages/astro/` | Astro integration |
| `packages/cli/` | CLI helpers |
| `packages/eslint-plugin/` | ESLint rules |
| `packages/vscode/` | VS Code snippets |

## What's NOT included

- ❌ Log levels (debug, info, warn, error) — execution tracing ≠ log routing
- ❌ Transport layers — we emit data, you decide where it goes
- ❌ SaaS dashboards — we don't host your logs
- ❌ Auto-instrumentation — you control what gets traced

## License

MIT