loggily 0.3.0 → 0.4.0

package/CLAUDE.md

@@ -1,299 +0,0 @@
-# loggily
-
-Structured logging with spans. Logger-first architecture: Span = Logger + Duration.
-
-## Quick Start
-
-```typescript
-import { createLogger } from "loggily"
-const log = createLogger("myapp")
-
-log.info("starting")
-log.error(new Error("failed"))
-
-// Spans for timing (implements Disposable)
-{
-  using span = log.span("import", { file: "data.csv" })
-  span.info("working...")
-  span.spanData.count = 42
-}
-// → SPAN myapp:import (15ms) {count: 42, file: "data.csv"}
-```
-
-## Environment Variables
-
-| Variable     | Values                                  | Effect                     |
-| ------------ | --------------------------------------- | -------------------------- |
-| LOG_LEVEL    | trace, debug, info, warn, error, silent | Filter output by level     |
-| DEBUG        | \*, namespace prefixes, -prefix         | Filter output by namespace |
-| TRACE        | 1, true, or namespace prefixes          | Enable span output         |
-| TRACE_FORMAT | json                                    | Force JSON output          |
-| NODE_ENV     | production                              | Auto-enable JSON format    |
-
-### Examples
-
-```bash
-LOG_LEVEL=debug bun run app         # Enable debug logging
-DEBUG=km:storage bun run app        # Only show km:storage (+ children), auto-enables debug level
-DEBUG='km:*,-km:sql' bun run app    # Show all km namespaces except km:sql
-DEBUG='*' bun run app               # Show all namespaces at debug level
-TRACE=1 bun run app                 # Enable all span timing output
-TRACE=myapp:import bun run app      # Enable spans for specific namespace
-TRACE=myapp,other bun run app       # Enable spans for multiple prefixes
-```
-
-## API
-
-### createLogger(name, props?)
-
-Create a logger. Props are inherited by children.
-
-```typescript
-const log = createLogger("myapp", { version: "1.0" })
-```
-
-### Logger Methods
-
-| Method                        | Purpose            |
-| ----------------------------- | ------------------ |
-| `.trace(msg, data?)`          | Verbose debugging  |
-| `.debug(msg, data?)`          | Debug information  |
-| `.info(msg, data?)`           | Normal operation   |
-| `.warn(msg, data?)`           | Recoverable issues |
-| `.error(msg \| Error, data?)` | Failures           |
-
-### Child Loggers
-
-```typescript
-// Extend namespace, inherit props
-const child = log.logger("import", { file: "data.csv" })
-// → namespace: "myapp:import", props: { version: "1.0", file: "data.csv" }
-
-// Create span (child with timing)
-{
-  using span = log.span("import")
-  span.info("working...")
-}
-```
-
-### Spans
-
-Spans are loggers with timing. They implement `Disposable` for use with `using`:
-
-```typescript
-{
-  using span = log.span("operation", { context: "value" })
-  span.debug("step 1")
-  span.spanData.processed = 100 // Set custom attributes
-}
-// On block exit: SPAN myapp:operation (15ms) {processed: 100, context: "value"}
-```
-
-For environments without `using` support, call `.end()` manually:
-
-```typescript
-const span = log.span("operation")
-try {
-  span.info("working...")
-  span.spanData.count = 42
-} finally {
-  span.end()
-}
-```
-
-### Span Data
-
-| Property             | Type                      | Description                           |
-| -------------------- | ------------------------- | ------------------------------------- |
-| `spanData.id`        | string (readonly)         | Unique span ID (sp_1, sp_2...)        |
-| `spanData.traceId`   | string (readonly)         | Trace ID (shared across nested spans) |
-| `spanData.parentId`  | string \| null (readonly) | Parent span ID                        |
-| `spanData.startTime` | number (readonly)         | Start timestamp (ms)                  |
-| `spanData.duration`  | number (readonly)         | Live duration since start             |
-| `spanData.custom`    | any (writable)            | Set custom attributes                 |
-
-### Configuration Functions
-
-```typescript
-import {
-  setLogLevel,
-  getLogLevel,
-  enableSpans,
-  disableSpans,
-  spansAreEnabled,
-  setTraceFilter,
-  getTraceFilter,
-  setDebugFilter,
-  getDebugFilter,
-} from "loggily"
-
-setLogLevel("debug") // Set minimum level
-getLogLevel() // Get current level: "debug"
-enableSpans() // Enable span output
-disableSpans() // Disable span output
-spansAreEnabled() // Check if spans are enabled
-setTraceFilter(["myapp"]) // Only output spans for "myapp" and "myapp:*"
-setTraceFilter(null) // Clear filter, output all spans
-getTraceFilter() // Get current filter: ["myapp"] or null
-setDebugFilter(["myapp"]) // Only show output for "myapp" and "myapp:*"
-setDebugFilter(["myapp", "-myapp:sql"]) // Show myapp but exclude myapp:sql
-setDebugFilter(null) // Clear filter, show all namespaces
-getDebugFilter() // Get current filter: ["myapp", "-myapp:sql"] or null
-```
-
-## Distributed Tracing (opt-in)
-
-### ID Format
-
-```typescript
-import { setIdFormat, getIdFormat } from "loggily"
-
-setIdFormat("simple") // sp_1, tr_1 (default)
-setIdFormat("w3c") // 16-char hex span, 32-char hex trace (W3C Trace Context)
-```
-
-### traceparent Header
-
-```typescript
-import { traceparent } from "loggily"
-
-const span = log.span("http-request")
-const header = traceparent(span.spanData)
-// → "00-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6-1a2b3c4d5e6f7a8b-01"
-fetch(url, { headers: { traceparent: header } })
-```
-
-### Sampling
-
-```typescript
-import { setSampleRate, getSampleRate } from "loggily"
-
-setSampleRate(0.1) // Sample 10% of traces (head-based)
-setSampleRate(1.0) // Sample everything (default)
-```
-
-### Context Propagation (Node.js/Bun only)
-
-```typescript
-import { enableContextPropagation, getCurrentSpan } from "loggily/context"
-
-enableContextPropagation()
-
-const log = createLogger("myapp")
-{
-  using span = log.span("request")
-  // Logs auto-tagged with trace_id/span_id
-  log.info("handling") // includes trace_id, span_id in output
-
-  // Child spans from ANY logger auto-parent via AsyncLocalStorage
-  const other = createLogger("db")
-  const dbSpan = other.span("query") // parentId = span.id
-
-  getCurrentSpan() // { spanId, traceId, parentId }
-}
-```
-
-## Output Format
-
-### Console (development)
-
-```
-14:32:15 INFO myapp starting
-14:32:15 DEBUG myapp:import loading {file: "data.csv"}
-14:32:16 SPAN myapp:import (1234ms) {count: 42}
-```
-
-### JSON (production / TRACE_FORMAT=json)
-
-```json
-{"time":"2024-01-15T14:32:15.123Z","level":"info","name":"myapp","msg":"starting"}
-{"time":"2024-01-15T14:32:16.456Z","level":"span","name":"myapp:import","msg":"(1234ms)","duration":1234,"count":42}
-```
-
-## Zero-Overhead Pattern (Optional Chaining)
-
-`createLogger` returns `undefined` for disabled log levels, enabling zero-overhead logging.
-
-**Log levels** (most → least verbose): `trace < debug < info < warn < error < silent`
-**Default level**: `warn` for km CLI (trace, debug, and info disabled)
-
-```typescript
-import { createLogger } from "loggily"
-
-const log = createLogger("km:tui")
-
-// All methods support ?. for zero-overhead when their level is disabled
-log.trace?.(`very verbose: ${expensiveDebug()}`) // Skipped at default (warn)
-log.debug?.(`state: ${getState()}`) // Skipped at default (warn)
-log.info?.("starting") // Skipped at default (warn)
-log.warn?.("deprecated") // Enabled at default (warn)
-log.error?.("failed") // Enabled at default
-
-// With -v flag or LOG_LEVEL=info, info is enabled:
-log.info?.("starting") // Enabled when level=info
-```
-
-### Why optional chaining?
-
-**Benchmark results** (10M iterations, Bun 1.1.x):
-
-| Scenario                  | ops/s    | ns/op   | Notes                               |
-| ------------------------- | -------- | ------- | ----------------------------------- |
-| noop (cheap args)         | 2168M    | 0.5     | Fastest for trivial args            |
-| `?.` (cheap args)         | 1406M    | 0.7     | ~0.2ns overhead - negligible        |
-| noop (expensive args)     | 17M      | 57.6    | Args still evaluated - wasted!      |
-| **`?.` (expensive args)** | **408M** | **2.5** | Args NOT evaluated - **22x faster** |
-
-**Key insight**: Optional chaining is only ~0.2ns slower for cheap args, but **22x faster** for expensive args because it skips argument evaluation entirely.
-
-- `log.debug?.()` skips the entire call including argument evaluation when debug is disabled
-- TypeScript enforces `?.` at compile time (methods are typed as possibly undefined)
-- Main benefit: expensive string formatting and function calls are completely skipped
-
-See [docs/conditional-logging-research.md](docs/conditional-logging-research.md) for detailed research and external references.
-
-## Lazy Messages
-
-Messages can be functions — only called when the log level is enabled:
-
-```typescript
-log.debug?.(() => `expensive: ${JSON.stringify(bigObject)}`)
-// Function never called when debug is disabled
-```
-
-Type: `LazyMessage = string | (() => string)`
-
-## Child Context Loggers
-
-Create child loggers with additional structured context (not just namespace):
-
-```typescript
-const child = log.child({ requestId: "abc-123", userId: 42 })
-child.info?.("handling request")
-// → 14:32:15 INFO myapp handling request {requestId: "abc-123", userId: 42}
-```
-
-## JSON Output Format
-
-```bash
-LOG_FORMAT=json bun run app   # Force JSON output in any environment
-```
-
-In addition to `TRACE_FORMAT=json` and `NODE_ENV=production`, `LOG_FORMAT=json` explicitly enables structured JSON output.
-
-## File Writer
-
-```typescript
-import { createFileWriter } from "loggily"
-
-const writer = createFileWriter("/tmp/app.log")
-const log = createLogger("myapp", { writer })
-```
-
-## Best Practices
-
-1. **Namespace hierarchy**: Use `:` to create hierarchy (`myapp:db:query`)
-2. **Props for context**: Pass structured data, not string interpolation
-3. **Spans for timing**: Wrap operations you want to measure
-4. **Level filtering**: Use `LOG_LEVEL` to control verbosity
-5. **Conditional logging**: Use `?.` pattern in hot paths to skip arg evaluation

package/CONTRIBUTING.md

@@ -1,58 +0,0 @@
-# Contributing to loggily
-
-## Development Setup
-
-```bash
-git clone https://github.com/beorn/loggily.git
-cd logger
-bun install
-bun run test        # Run tests
-bun run typecheck   # Type check
-```
-
-## Code Style
-
-- TypeScript strict mode
-- ESM imports only (`import`/`export`, never `require`)
-- Factory functions over classes
-- Zero external dependencies
-
-## Testing
-
-All changes should include tests. Run the test suite before submitting:
-
-```bash
-bun run test
-```
-
-Tests must be silent on success. Use `vi.spyOn(console, 'log').mockImplementation(() => {})` to suppress output in tests.
-
-## Pull Requests
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Make your changes with tests
-4. Ensure `bun run test` and `bun run typecheck` pass
-5. Commit with [conventional commit](https://conventionalcommits.org/) messages
-6. Push and open a pull request
-
-## Commit Messages
-
-- `feat:` -- New features
-- `fix:` -- Bug fixes
-- `docs:` -- Documentation only
-- `test:` -- Test additions
-- `refactor:` -- Code changes that neither fix bugs nor add features
-- `chore:` -- Maintenance tasks
-
-## Design Principles
-
-1. **Logger-first** -- Spans are loggers with timing, not separate concepts
-2. **Minimal surface** -- Few, well-designed functions
-3. **Type safe** -- TypeScript enforces correct usage (e.g., `?.` for disabled levels)
-4. **Zero-cost** -- Optional chaining skips argument evaluation when disabled
-5. **Structured** -- JSON in production, readable console in development
-
-## Questions?
-
-Open an issue for discussion before starting large changes.

package/benchmarks/overhead.ts

@@ -1,267 +0,0 @@
-/**
- * loggily Benchmark Suite
- *
- * Compares zero-overhead disabled logging and enabled logging performance
- * against popular alternatives: pino, winston, debug.
- *
- * All "enabled" benchmarks use the same kind of sink (noop writer) for a fair
- * apples-to-apples comparison of formatting + serialization throughput.
- *
- * Run: bun benchmarks/overhead.ts
- */
-
-import { addWriter, createLogger, setLogLevel, setOutputMode, setSuppressConsole, disableSpans } from "../src/index.ts"
-
-// ── Helpers ──────────────────────────────────────────────────────────────────
-
-function measure(
-  name: string,
-  fn: () => void,
-  iterations: number,
-): { name: string; opsPerSec: number; nsPerOp: number } {
-  // Warmup
-  for (let i = 0; i < 1000; i++) fn()
-
-  const start = Bun.nanoseconds()
-  for (let i = 0; i < iterations; i++) fn()
-  const elapsed = Bun.nanoseconds() - start
-
-  const nsPerOp = elapsed / iterations
-  const opsPerSec = 1e9 / nsPerOp
-
-  return { name, opsPerSec, nsPerOp }
-}
-
-function formatOps(ops: number): string {
-  if (ops >= 1e9) return `${(ops / 1e9).toFixed(0)}B`
-  if (ops >= 1e6) return `${(ops / 1e6).toFixed(0)}M`
-  if (ops >= 1e3) return `${(ops / 1e3).toFixed(0)}K`
-  return `${ops.toFixed(0)}`
-}
-
-function formatNs(ns: number): string {
-  if (ns >= 1e6) return `${(ns / 1e6).toFixed(1)}ms`
-  if (ns >= 1e3) return `${(ns / 1e3).toFixed(1)}µs`
-  return `${ns.toFixed(1)}ns`
-}
-
-function printResults(title: string, results: Array<{ name: string; opsPerSec: number; nsPerOp: number }>) {
-  console.log(`\n${title}`)
-  console.log("─".repeat(70))
-
-  const maxNameLen = Math.max(...results.map((r) => r.name.length))
-
-  for (const r of results) {
-    const name = r.name.padEnd(maxNameLen)
-    const ops = formatOps(r.opsPerSec).padStart(6)
-    const ns = formatNs(r.nsPerOp).padStart(8)
-    console.log(`  ${name}  ${ops} ops/s  ${ns}/op`)
-  }
-}
-
-// ── Expensive argument simulation ────────────────────────────────────────────
-
-function expensiveArg(): string {
-  return JSON.stringify({ a: 1, b: 2, c: [3, 4, 5], d: { e: "hello", f: true } })
-}
-
-// ── Noop stream (shared sink type for fair enabled comparisons) ──────────────
-
-const { Writable } = await import("stream")
-const noopStream = () =>
-  new Writable({
-    write(_chunk: unknown, _encoding: string, callback: () => void) {
-      callback()
-    },
-  })
-
-// ── loggily setup ──────────────────────────────────────────────────────
-
-const beornLog = createLogger("bench")
-// Route all output to noop writer, suppress console
-setSuppressConsole(true)
-setOutputMode("writers-only")
-addWriter(() => {}) // noop writer — receives formatted output, discards it
-disableSpans()
-
-// ── Pino setup ───────────────────────────────────────────────────────────────
-
-type LogFn = {
-  (msg: string): void
-  (obj: Record<string, unknown>, msg: string): void
-}
-
-interface BenchLogger {
-  debug: LogFn
-  info: LogFn
-  warn: LogFn
-}
-
-// Disabled pino (level=warn, debug/info disabled) — second arg = noop stream
-// Enabled pino (level=debug, all levels active) — second arg = noop stream
-let pinoDisabled: BenchLogger
-let pinoEnabled: BenchLogger
-try {
-  const pino = (await import("pino")).default
-  pinoDisabled = pino({ level: "warn" }, noopStream())
-  pinoEnabled = pino({ level: "debug" }, noopStream())
-} catch {
-  console.log("pino not installed — install with: bun add -d pino")
-  const stub: BenchLogger = { debug: () => {}, info: () => {}, warn: () => {} }
-  pinoDisabled = stub
-  pinoEnabled = stub
-}
-
-// ── Winston setup ────────────────────────────────────────────────────────────
-
-// Disabled winston (level=warn, debug/info disabled)
-// Enabled winston (level=debug, all levels active) — noop stream transport
-let winstonDisabled: BenchLogger
-let winstonEnabled: BenchLogger
-try {
-  const winston = await import("winston")
-  winstonDisabled = winston.createLogger({
-    level: "warn",
-    transports: [new winston.transports.Console({ silent: true })],
-  })
-  winstonEnabled = winston.createLogger({
-    level: "debug",
-    transports: [new winston.transports.Stream({ stream: noopStream() })],
-  })
-} catch {
-  console.log("winston not installed — install with: bun add -d winston")
-  const stub: BenchLogger = { debug: () => {}, info: () => {}, warn: () => {} }
-  winstonDisabled = stub
-  winstonEnabled = stub
-}
-
-// ── Debug setup ──────────────────────────────────────────────────────────────
-
-let debugFn: (msg: string) => void
-try {
-  const debug = (await import("debug")).default
-  debugFn = debug("bench") // DEBUG env not set → disabled
-} catch {
-  console.log("debug not installed — install with: bun add -d debug")
-  debugFn = () => {}
-}
-
-// ── Baseline: noop ───────────────────────────────────────────────────────────
-
-const noop = (): void => {}
-
-// ── Benchmarks ───────────────────────────────────────────────────────────────
-
-const N = 10_000_000
-
-console.log("loggily Benchmark Suite")
-console.log(`Iterations: ${(N / 1e6).toFixed(0)}M per test`)
-console.log(`Runtime: Bun ${Bun.version}`)
-console.log(`Platform: ${process.platform} ${process.arch}`)
-
-// ─── PART 1: DISABLED LOGGING ────────────────────────────────────────────────
-
-// 1. Disabled debug call — cheap args
-{
-  setLogLevel("warn") // debug disabled
-
-  const results = [
-    measure("noop()", () => noop(), N),
-    measure("beorn: log.debug?.(str)", () => beornLog.debug?.("hello"), N),
-    measure("pino: log.debug(str)", () => pinoDisabled.debug("hello"), N),
-    measure("winston: log.debug(str)", () => winstonDisabled.debug("hello"), N),
-    measure('debug: debug("hello")', () => debugFn("hello"), N),
-  ]
-
-  printResults("DISABLED DEBUG — cheap argument (string literal)", results)
-}
-
-// 2. Disabled debug call — expensive args
-{
-  setLogLevel("warn") // debug disabled
-
-  const results = [
-    measure("noop(expensive)", () => noop(), N),
-    measure("beorn: log.debug?.(expensive)", () => beornLog.debug?.(`state: ${expensiveArg()}`), N),
-    measure("pino: log.debug(expensive)", () => pinoDisabled.debug(`state: ${expensiveArg()}`), N),
-    measure("winston: log.debug(expensive)", () => winstonDisabled.debug(`state: ${expensiveArg()}`), N),
-    measure("debug: debug(expensive)", () => debugFn(`state: ${expensiveArg()}`), N),
-  ]
-
-  printResults("DISABLED DEBUG — expensive argument (JSON.stringify)", results)
-}
-
-// ─── PART 2: ENABLED LOGGING (all to noop writers) ───────────────────────────
-// Fair comparison: all loggers format + serialize, all write to noop sinks.
-// beorn: addWriter(noop) + setSuppressConsole(true) + setOutputMode("writers-only")
-// pino: pino(opts, noopWritableStream)
-// winston: Stream transport with noop Writable
-
-// 3. Enabled info — cheap args (string literal)
-{
-  setLogLevel("info") // info enabled
-
-  const results = [
-    measure("beorn: log.info?.(str)", () => beornLog.info?.("hello"), N / 10),
-    measure("pino: log.info(str)", () => pinoEnabled.info("hello"), N / 10),
-    measure("winston: log.info(str)", () => winstonEnabled.info("hello"), N / 10),
-  ]
-
-  printResults("ENABLED INFO — cheap argument (string literal) — all to noop sink", results)
-}
-
-// 4. Enabled info — structured data
-{
-  setLogLevel("info") // info enabled
-
-  const structuredData = { key: "value", count: 42 }
-
-  const results = [
-    measure("beorn: log.info?.(str, data)", () => beornLog.info?.("request", structuredData), N / 10),
-    measure("pino: log.info(obj, str)", () => pinoEnabled.info(structuredData, "request"), N / 10),
-    measure("winston: log.info(str, data)", () => winstonEnabled.info("request", structuredData), N / 10),
-  ]
-
-  printResults("ENABLED INFO — structured data ({ key, count }) — all to noop sink", results)
-}
-
-// 5. Enabled warn — with Error object
-{
-  setLogLevel("warn") // warn enabled
-
-  const err = new Error("something broke")
-
-  const results = [
-    measure("beorn: log.warn?.(Error)", () => beornLog.warn?.(err), N / 10),
-    measure("pino: log.warn(Error)", () => pinoEnabled.warn({ err }, "something broke"), N / 10),
-    measure("winston: log.warn(str, Error)", () => winstonEnabled.warn("something broke", { error: err }), N / 10),
-  ]
-
-  printResults("ENABLED WARN — Error object — all to noop sink", results)
-}
-
-// ─── PART 3: SPANS ──────────────────────────────────────────────────────────
-
-// 6. Span creation + disposal
-{
-  setLogLevel("warn")
-  disableSpans()
-
-  const results = [
-    measure(
-      "beorn: span create+dispose",
-      () => {
-        using _s = beornLog.span("op")
-      },
-      N / 10,
-    ),
-  ]
-
-  printResults("SPAN — create + dispose (no output)", results)
-}
-
-console.log("\n" + "─".repeat(70))
-console.log("Key: ops/s = operations per second, /op = time per operation")
-console.log("beorn uses ?. for zero-overhead: disabled calls skip argument evaluation")
-console.log("Enabled benchmarks: all loggers write to noop sinks (fair comparison)")
-console.log("")