loggily 0.0.1 → 0.3.0

package/docs/comparison.md

@@ -0,0 +1,315 @@
+# 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

@@ -0,0 +1,159 @@
+# 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

@@ -0,0 +1,205 @@
+# 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.