loggily 0.3.0 → 0.4.1

package/docs/comparison.md

@@ -1,315 +0,0 @@
-# Comparison with Other Loggers
-
-How loggily compares to popular Node.js logging libraries.
-
-## Feature Comparison Table
-
-| Feature                | loggily     | Pino    | Winston   | Bunyan    | debug     |
-| ---------------------- | ----------- | ------- | --------- | --------- | --------- |
-| **Log Levels**         | Yes (5)     | Yes (6) | Yes (7)   | Yes (6)   | No        |
-| **Structured Logging** | Yes         | Yes     | Yes       | Yes       | No        |
-| **JSON Output**        | Yes         | Yes     | Yes       | Yes       | No        |
-| **Spans/Tracing**      | Built-in    | No      | No        | No        | No        |
-| **Zero-cost Disabled** | Yes (`?.`)  | No      | No        | No        | No        |
-| **Child Loggers**      | Yes         | Yes     | Yes       | Yes       | Manual    |
-| **Transports**         | File writer | Yes     | Yes       | Yes       | No        |
-| **Pretty Print**       | Auto (dev)  | Plugin  | Plugin    | Plugin    | Yes       |
-| **Browser Support**    | Partial     | Yes     | Yes       | Yes       | Yes       |
-| **Bundle Size**        | ~3KB        | ~17KB   | ~200KB+   | ~30KB     | ~2KB      |
-| **TypeScript**         | Native      | Yes     | Types pkg | Types pkg | Types pkg |
-
-## vs Pino
-
-[Pino](https://github.com/pinojs/pino) is the gold standard for high-performance Node.js logging.
-
-### Similarities
-
-- Performance-focused design
-- JSON output in production
-- Child loggers with inherited context
-- Minimal overhead
-
-### Differences
-
-| Aspect             | Pino                           | loggily                            |
-| ------------------ | ------------------------------ | ---------------------------------- |
-| Zero-cost disabled | Noop function (args evaluated) | Optional chaining (args skipped)   |
-| Spans              | External (pino-opentelemetry)  | Built-in                           |
-| Transports         | Built-in (worker threads)      | File writer + custom via addWriter |
-| Formatters         | Plugin system                  | Console/JSON auto-switch           |
-| Serializers        | Configurable                   | Fixed (Error auto-handled)         |
-
-### When to Choose
-
-**Choose Pino if:**
-
-- You need transport plugins (file rotation, remote logging)
-- You need custom serializers for complex objects
-- You're building a large production system with multiple log destinations
-
-**Choose loggily if:**
-
-- You want zero-cost disabled logging via optional chaining
-- You need built-in span timing
-- You prefer simplicity over configuration
-- Bundle size matters
-
-### Code Comparison
-
-```typescript
-// Pino
-import pino from "pino"
-const log = pino({ level: "debug" })
-const child = log.child({ requestId: "123" })
-child.info({ user: "alice" }, "logged in")
-
-// loggily
-import { createLogger } from "loggily"
-const log = createLogger("myapp")
-const child = log.logger("request", { requestId: "123" })
-child.info("logged in", { user: "alice" })
-```
-
----
-
-## vs Winston
-
-[Winston](https://github.com/winstonjs/winston) is the most popular Node.js logger with extensive transport support.
-
-### Similarities
-
-- Multiple log levels
-- Structured logging support
-- Child loggers
-
-### Differences
-
-| Aspect        | Winston                | loggily             |
-| ------------- | ---------------------- | ------------------- |
-| Philosophy    | Flexible, configurable | Simple, opinionated |
-| Transports    | 10+ built-in           | stdout only         |
-| Configuration | Extensive              | Minimal (env vars)  |
-| Performance   | Moderate               | High                |
-| Bundle Size   | ~200KB+                | ~3KB                |
-| Spans         | No                     | Built-in            |
-
-### When to Choose
-
-**Choose Winston if:**
-
-- You need multiple transports (file, HTTP, database)
-- You need custom formatters and filters
-- You have complex logging requirements
-
-**Choose loggily if:**
-
-- You want minimal configuration
-- Performance is critical
-- You're logging to stdout (12-factor app)
-- You need built-in timing spans
-
-### Code Comparison
-
-```typescript
-// Winston
-import winston from "winston"
-const log = winston.createLogger({
-  level: "info",
-  format: winston.format.json(),
-  transports: [new winston.transports.Console()],
-})
-log.info("starting", { port: 3000 })
-
-// loggily
-import { createLogger } from "loggily"
-const log = createLogger("myapp")
-log.info("starting", { port: 3000 })
-```
-
----
-
-## vs Bunyan
-
-[Bunyan](https://github.com/trentm/node-bunyan) focuses on JSON logging with built-in CLI tools.
-
-### Similarities
-
-- JSON-first output
-- Child loggers
-- Structured data
-
-### Differences
-
-| Aspect        | Bunyan                 | loggily                     |
-| ------------- | ---------------------- | --------------------------- |
-| Output Format | JSON only              | Console (dev) / JSON (prod) |
-| CLI Tools     | bunyan CLI for viewing | None                        |
-| Streams       | Multiple streams       | stdout only                 |
-| Spans         | No                     | Built-in                    |
-| API           | Verbose                | Simple                      |
-
-### When to Choose
-
-**Choose Bunyan if:**
-
-- You want the bunyan CLI for log viewing
-- You need multiple output streams
-- JSON-only output is fine for development
-
-**Choose loggily if:**
-
-- You want readable console output in development
-- You need built-in spans
-- You prefer a simpler API
-
-### Code Comparison
-
-```typescript
-// Bunyan
-import bunyan from "bunyan"
-const log = bunyan.createLogger({ name: "myapp" })
-const child = log.child({ requestId: "123" })
-child.info({ user: "alice" }, "logged in")
-
-// loggily
-import { createLogger } from "loggily"
-const log = createLogger("myapp")
-const child = log.logger("request", { requestId: "123" })
-child.info("logged in", { user: "alice" })
-```
-
----
-
-## vs debug
-
-[debug](https://github.com/debug-js/debug) is a tiny debugging utility.
-
-### Similarities
-
-- Minimal footprint
-- Namespace-based organization
-- Environment variable control
-
-### Differences
-
-| Aspect        | debug             | loggily           |
-| ------------- | ----------------- | ----------------- |
-| Log Levels    | No (on/off)       | Yes (5 levels)    |
-| Output Format | printf-style      | Structured JSON   |
-| Spans         | No                | Built-in          |
-| Conditional   | `.enabled` check  | Optional chaining |
-| Data          | Inline in message | Separate object   |
-
-### When to Choose
-
-**Choose debug if:**
-
-- You only need simple debugging output
-- You don't need log levels
-- You don't need structured data
-
-**Choose loggily if:**
-
-- You need log levels
-- You need structured data
-- You need timing spans
-- You want zero-cost disabled logging
-
-### Code Comparison
-
-```typescript
-// debug
-import createDebug from "debug"
-const debug = createDebug("myapp")
-debug("user %s logged in", username)
-
-// loggily
-import { createLogger } from "loggily"
-const log = createLogger("myapp")
-log.info("user logged in", { username })
-```
-
-See [migration-from-debug.md](./migration-from-debug.md) for a detailed migration guide.
-
----
-
-## Unique Features of loggily
-
-### 1. Zero-cost Disabled Logging
-
-Optional chaining skips argument evaluation entirely:
-
-```typescript
-// Other loggers - args always evaluated
-pino.debug(`expensive: ${computeState()}`) // computeState() runs even if disabled
-
-// loggily - args skipped when disabled
-log.debug?.(`expensive: ${computeState()}`) // computeState() NOT called if disabled
-```
-
-**Benchmark (10M iterations):**
-
-- Noop with expensive args: 17M ops/s (57.6ns)
-- Optional chaining with expensive args: 408M ops/s (2.5ns) - **22x faster**
-
-### 2. Built-in Spans
-
-No external tracing library needed:
-
-```typescript
-{
-  using span = log.span("db:query", { table: "users" })
-  const users = await db.query("SELECT * FROM users")
-  span.spanData.count = users.length
-}
-// → SPAN myapp:db:query (45ms) {count: 100, table: "users"}
-```
-
-Features:
-
-- Automatic timing on block exit
-- Parent-child relationships tracked
-- Custom attributes via `spanData`
-- Trace ID for request correlation
-
-### 3. Disposable Pattern
-
-Uses JavaScript's `using` keyword for automatic cleanup:
-
-```typescript
-{
-  using span = log.span("operation")
-  // ... work ...
-} // Span automatically ends and emits timing
-
-// No need for try/finally or .end() calls
-```
-
-### 4. Auto-format Switching
-
-Console output in development, JSON in production:
-
-```bash
-# Development (pretty console)
-bun run app
-# → 14:32:15 INFO myapp starting {port: 3000}
-
-# Production (JSON)
-NODE_ENV=production bun run app
-# → {"time":"2024-01-15T14:32:15.123Z","level":"info","name":"myapp","msg":"starting","port":3000}
-```
-
----
-
-## Summary
-
-| Use Case                                | Recommended      |
-| --------------------------------------- | ---------------- |
-| High-performance with optional chaining | loggily          |
-| Built-in span timing                    | loggily          |
-| Multiple transports                     | Pino or Winston  |
-| Extensive configuration                 | Winston          |
-| JSON CLI tools                          | Bunyan           |
-| Simple debugging only                   | debug            |
-| Minimal bundle size                     | debug or loggily |
-| TypeScript-first                        | loggily or Pino  |

package/docs/conditional-logging-research.md

@@ -1,159 +0,0 @@
-# Conditional Logging Research
-
-Background research for the optional chaining pattern in loggily.
-
-## The Problem
-
-When logging is disabled, traditional loggers still evaluate arguments:
-
-```typescript
-// Even when debug is disabled, expensiveState() is STILL called
-log.debug("state: %o", computeExpensiveState())
-```
-
-This is wasted work. In hot code paths (rendering loops, per-node operations), this overhead adds up.
-
-## Solution: Optional Chaining
-
-JavaScript's optional chaining (`?.`) skips argument evaluation entirely when the method is undefined:
-
-```typescript
-// When log.debug is undefined, the entire call is skipped
-// computeExpensiveState() is NEVER called
-log.debug?.("state: %o", computeExpensiveState())
-```
-
-## Benchmark Results (Bun 1.1.x, M1 Mac)
-
-```
-DISABLED LOGGING (no arguments evaluated)
-1. noop function call                         2168M ops/s  0.5ns/op
-2. optional chaining (?.) - undefined         1406M ops/s  0.7ns/op
-3. proxy returning undefined + ?.              545M ops/s  1.8ns/op
-4. proxy returning noop                        352M ops/s  2.8ns/op
-
-DISABLED LOGGING (with expensive argument)
-1. noop - args evaluated (wastes work)          17M ops/s  57.6ns/op
-2. optional chaining - args NOT evaluated      408M ops/s   2.5ns/op  ← 22x faster
-3. proxy + ?. - args NOT evaluated             168M ops/s   5.9ns/op
-4. proxy + noop - args evaluated (wastes work)  15M ops/s  65.3ns/op
-```
-
-**Key insight**: For cheap arguments, noop is only ~0.2ns faster. For expensive arguments, optional chaining is **22x faster** because it skips argument evaluation entirely.
-
-## External Research
-
-### Matteo Collina's Analysis (2025)
-
-Article: [Noop Functions vs Optional Chaining: A Performance Deep Dive](https://adventures.nodeland.dev/archive/noop-functions-vs-optional-chaining-a-performance/)
-
-Collina (Pino maintainer) benchmarked that noop functions outperform optional chaining in raw call overhead. However, his test used cheap arguments. The benchmark above shows that the **real benefit** of `?.` is skipping expensive argument evaluation, which Collina's test didn't measure.
-
-Quote: "Discover why noop functions are faster than optional chaining in JavaScript"
-
-**Our finding**: This is only true for cheap args. When args are expensive, `?.` wins decisively.
-
-### Lazy Logging in JavaScript (2023)
-
-Article: [Lazy/conditional logging in JavaScript](https://tonisives.com/blog/2023/05/28/lazy-conditional-logging-in-javascript/)
-
-Toni Sives describes passing functions to delay evaluation:
-
-```typescript
-Logger.trace(() => `long task took ${longRunningTask()}`)
-```
-
-This works but requires wrapping every call in an arrow function. Optional chaining is more ergonomic:
-
-```typescript
-log.trace?.(`long task took ${longRunningTask()}`)
-```
-
-### TC39 Explicit Resource Management
-
-The `using` keyword (Stage 3 as of June 2024) enables automatic span disposal:
-
-```typescript
-{
-  using span = log.span("operation")
-  span.debug("working...")
-} // Automatically calls span[Symbol.dispose]()
-```
-
-Reference: [TC39 Proposal](https://tc39.es/proposal-explicit-resource-management/)
-
-### Proxy Performance (Historical)
-
-Valeri Karpov's 2016 benchmarks showed Proxies were ~10x slower than direct property access. Modern V8 has improved significantly, but Proxy still adds overhead (~1-3ns per access). For logging, this is negligible compared to actual I/O.
-
-Reference: [Thoughts on ES6 Proxies Performance](https://thecodebarbarian.com/thoughts-on-es6-proxies-performance)
-
-## Implementation Approach
-
-### Proxy Wrapper
-
-```typescript
-import { createLogger, getLogLevel } from "loggily"
-
-const baseLog = createLogger("myapp")
-
-const LEVEL_PRIORITY = {
-  trace: 0,
-  debug: 1,
-  info: 2,
-  warn: 3,
-  error: 4,
-  silent: 5,
-}
-
-export const log = new Proxy(baseLog, {
-  get(target, prop: string) {
-    // For level methods, return undefined if disabled
-    if (prop in LEVEL_PRIORITY) {
-      const current = LEVEL_PRIORITY[getLogLevel() as keyof typeof LEVEL_PRIORITY]
-      if (LEVEL_PRIORITY[prop as keyof typeof LEVEL_PRIORITY] < current) {
-        return undefined
-      }
-    }
-    return (target as any)[prop]
-  },
-})
-```
-
-### TypeScript Types
-
-```typescript
-type ConditionalLogger = {
-  trace?: (msg: string, data?: object) => void
-  debug?: (msg: string, data?: object) => void
-  info?: (msg: string, data?: object) => void
-  warn?: (msg: string, data?: object) => void
-  error: (msg: string, data?: object) => void // Always available
-  logger: (ns?: string, props?: object) => ConditionalLogger
-  span?: (ns?: string, props?: object) => SpanLogger | undefined
-}
-```
-
-TypeScript enforces the `?.` pattern at compile time - you can't call `log.debug()` without `?.` because the method may be undefined.
-
-## Design Decision: Always Use `?.`
-
-Given the benchmark results:
-
-- Overhead of `?.` vs noop for cheap args: ~0.2ns (negligible)
-- Benefit of `?.` for expensive args: ~55ns saved (22x faster)
-
-**Conclusion**: Always use `log.debug?.()`. The ergonomic cost is minimal (just add `?.`), and the performance benefit is significant when arguments involve any computation.
-
-## Alternative: Lazy Evaluation
-
-For very expensive argument preparation, use a function:
-
-```typescript
-log.debug?.(() => {
-  const state = gatherComplexState()
-  return ["state: %o", state]
-})
-```
-
-The logger calls the function only if debug is enabled. This pattern is useful when you need to prepare multiple pieces of data that depend on each other.

package/docs/guide.md

@@ -1,205 +0,0 @@
-# The Guide
-
-> Clarity without the clutter. Ergonomic unified logs, spans, metrics, and debugs for modern TypeScript.
-
-Your first app uses `console.log`. That's enough for a script, a prototype, a small server. Then your app grows. You need structured logs for production, the `debug` package for conditional verbose output, a tracing library for timings, maybe OpenTelemetry for distributed traces — and suddenly you're juggling three tools with three APIs, three configuration schemes, and three output formats.
-
-loggily is one library where structured logging, debug-style conditional output, timed spans, and metrics all share the same namespace tree, the same output pipeline, and the same zero-overhead pattern. You adopt each capability when you need it. Nothing is wasted, nothing conflicts, nothing clutters your code.
-
-## Level 1: Just Log
-
-You need structured logging with levels. One import, one function.
-
-```typescript
-import { createLogger } from "loggily"
-
-const log = createLogger("myapp")
-
-log.info?.("server started", { port: 3000 })
-log.warn?.("disk space low", { free: "2GB" })
-log.error?.(new Error("connection failed"))
-```
-
-Notice the `?.` — if a log level is disabled, the entire call is skipped, including argument evaluation. In benchmarks, this makes disabled log calls ~22x faster than a traditional logger that still evaluates its arguments. You get zero-cost logging for disabled levels, not just low-cost.
-
-Colorized in your terminal, with source locations:
-
-```
-14:32:15 INFO myapp server started {port: 3000}
-14:32:15 WARN myapp disk space low {free: "2GB"}
-14:32:15 ERROR myapp connection failed
-  Error: connection failed
-    at server.ts:42
-```
-
-Set `LOG_FORMAT=json` or `NODE_ENV=production` and the same calls produce structured JSON — same data, machine-parseable, ready for Datadog or Elastic or whatever your ops team uses:
-
-```json
-{ "time": "2024-01-15T14:32:15.123Z", "level": "info", "name": "myapp", "msg": "server started", "port": 3000 }
-```
-
-You never choose between human-readable and machine-parseable. You get both from the same call.
-
-**The wall**: Your app has 20 modules. You need verbose output from the database layer but not from the HTTP layer. `LOG_LEVEL=debug` turns on everything.
-
-## Level 2: Namespaces
-
-Loggers form a tree. Child loggers inherit their parent's namespace and props:
-
-```typescript
-const log = createLogger("myapp")
-const db = log.logger("db") // myapp:db
-const http = log.logger("http") // myapp:http
-const query = db.logger("query") // myapp:db:query
-
-db.debug?.("connecting") // myapp:db
-query.debug?.("SELECT * FROM...") // myapp:db:query
-```
-
-Now you can target output. `DEBUG` auto-lowers the log level to `debug` and restricts all output to matching namespaces:
-
-```bash
-DEBUG=myapp:db bun run app                # Only myapp:db namespace (all levels)
-DEBUG='myapp:*,-myapp:http' bun run app   # Everything except HTTP
-LOG_LEVEL=debug bun run app               # Debug level globally, all namespaces
-```
-
-`DEBUG` is a namespace visibility filter inspired by the `debug` package — same patterns, same muscle memory — but as part of a full logging system with levels, structured data, and JSON output. Use `LOG_LEVEL` when you want to change the verbosity floor without restricting namespaces.
-
-**The wall**: A request takes 3 seconds. You know it's slow, but you don't know which part.
-
-## Level 3: Spans
-
-A span is a logger with a timer. It measures how long a block takes, and every log inside it inherits its context:
-
-```typescript
-{
-  using span = log.span("import", { file: "data.csv" })
-  span.info?.("parsing rows")
-  span.spanData.count = 42
-}
-// -> SPAN myapp:import (1234ms) {count: 42, file: "data.csv"}
-```
-
-The `using` keyword (TC39 Explicit Resource Management) automatically calls `span[Symbol.dispose]()` at block exit. The span measures its duration and reports it along with any attributes you set. No try/finally, no manual timing, no separate tracing SDK.
-
-Spans nest. Each span gets a unique ID and shares its parent's trace ID, so you can correlate events across a request:
-
-```typescript
-{
-  using req = log.span("request", { path: "/api/users" })
-  {
-    using db = req.span("db-query")
-    // db.spanData.traceId === req.spanData.traceId
-    // db.spanData.parentId === req.spanData.id
-  }
-}
-```
-
-Control span output independently from logs:
-
-```bash
-TRACE=1 bun run app                  # All spans
-TRACE=myapp:db bun run app           # Only database spans
-TRACE=myapp:db,myapp:cache bun run app  # Database + cache spans
-```
-
-**The wall**: Now you need logs sent elsewhere — a file, Datadog, your tracing backend — not just the console.
-
-## Level 4: Writers
-
-The writer system is a simple function interface. Write once, send anywhere:
-
-```typescript
-import { addWriter, createFileWriter } from "loggily"
-
-// File writer with buffered auto-flush
-const file = createFileWriter("/var/log/app.log")
-addWriter((formatted, level) => file.write(formatted))
-
-// Send to an HTTP endpoint
-addWriter((formatted, level) => {
-  if (level === "error") fetch("/api/alerts", { method: "POST", body: formatted })
-})
-
-// Send spans to your tracing backend
-addWriter((formatted, level) => {
-  if (level === "span") sendToJaeger(JSON.parse(formatted))
-})
-```
-
-You can attach multiple writers — each one receives every log and span. The logger doesn't care where the output goes; it just produces structured data. You decide where to send it.
-
-Output modes let you control the default output:
-
-```typescript
-import { setOutputMode } from "loggily"
-setOutputMode("writers-only") // Only writers, no console
-setOutputMode("stderr") // Bypass Ink/React console capture
-setOutputMode("console") // Default: console.log/warn/error
-```
-
-**The wall**: You spawn worker threads for heavy processing, but their logs vanish from the main output.
-
-## Level 5: Workers
-
-Worker threads get their own loggers that forward to the main thread:
-
-```typescript
-// worker.ts
-import { createWorkerLogger } from "loggily/worker"
-
-const log = createWorkerLogger(postMessage, "myapp:worker")
-log.info?.("processing chunk", { size: 1000 })
-
-{
-  using span = log.span("process")
-  // ...
-}
-```
-
-```typescript
-// main.ts
-import { createWorkerLogHandler } from "loggily/worker"
-
-const handler = createWorkerLogHandler()
-worker.on("message", (msg) => handler(msg))
-```
-
-Logs and spans from workers appear in the same output stream with the same formatting. No interleaving, no lost messages.
-
-**The wall**: You need child loggers that carry request context through async call chains without passing the logger everywhere.
-
-## Level 6: Context
-
-Child loggers carry structured context through async call chains. Create one at the request boundary, and every downstream log inherits its fields:
-
-```typescript
-const reqLog = log.child({ requestId: "abc-123", userId: 42 })
-
-reqLog.info?.("handling request")
-// -> 14:32:15 INFO myapp handling request {requestId: "abc-123", userId: 42}
-
-// Pass reqLog to downstream functions -- context propagates
-await handleAuth(reqLog)
-await handleQuery(reqLog)
-```
-
-Every log from `reqLog` and its descendants carries `requestId` and `userId` without manual field-passing. In JSON mode, these become top-level fields — perfect for filtering in your log aggregator.
-
-## What You Have
-
-Normally, you'd pull in one library for logs, another for debug prints, a tracing SDK for spans — and struggle to tie them together. With loggily, these aren't separate concerns. They're modes of the same tool.
-
-At this point you've replaced that patchwork with a single library:
-
-- **Structured logging** with levels, namespaces, colorized dev output, JSON production output, and source locations
-- **Debug output** with `DEBUG=namespace:*` filtering — the `debug` package's power, integrated
-- **Span timing** with `using` keyword, nested traces, and independent `TRACE=` control
-- **Flexible output** via writers — file, HTTP, tracing backends, anything
-- **Worker thread support** with automatic forwarding
-- **Context propagation** via child loggers
-
-All sharing one namespace tree. All respecting the same log levels. All using the same `?.` pattern — disabled calls are skipped entirely, including argument evaluation. There when you need it, invisible when you don't.
-
-~3KB. Zero dependencies. Modern TypeScript.