loggily 0.3.0 → 0.4.1

package/docs/site/guide/journey.md

@@ -1,203 +0,0 @@
-# The Journey
-
-> Clarity without the clutter.
-
-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:
-
-```
-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 Get
-
-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:
-
-- **Structured logging** with levels, namespaces, colorized dev output, JSON production output
-- **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.

package/docs/site/guide/migration-from-debug.md

@@ -1,24 +0,0 @@
-# Migration from debug
-
-See the [full migration guide](https://github.com/beorn/loggily/blob/main/docs/migration-from-debug.md) for step-by-step instructions.
-
-## Quick Overview
-
-```typescript
-// Before (debug)
-import createDebug from "debug"
-const debug = createDebug("myapp")
-debug("user %s logged in from %s", username, ip)
-
-// After (loggily)
-import { createLogger } from "loggily"
-const log = createLogger("myapp")
-log.info?.("user logged in", { username, ip })
-```
-
-The `DEBUG` environment variable works the same way:
-
-```bash
-DEBUG=myapp bun run app
-DEBUG='myapp,-myapp:noisy' bun run app
-```

package/docs/site/guide/spans.md

@@ -1,139 +0,0 @@
-# Spans
-
-Spans are loggers with timing. Call `.span()` and it creates a child logger that tracks how long the block runs.
-
-## Basic Usage
-
-```typescript
-{
-  using span = log.span("import", { file: "data.csv" })
-  span.info?.("parsing rows")
-  const rows = await parseFile()
-  span.spanData.rowCount = rows.length
-}
-// SPAN myapp:import (1234ms) {rowCount: 500, file: "data.csv"}
-```
-
-The `using` keyword (TC39 Explicit Resource Management) calls `span[Symbol.dispose]()` when the block exits, which records the end time and emits the span event.
-
-## Enabling Spans
-
-Span output is off by default. Enable via environment or code:
-
-```bash
-TRACE=1 bun run app              # All spans
-TRACE=myapp:db bun run app       # Only db spans
-TRACE=myapp,other bun run app    # Multiple namespaces
-```
-
-```typescript
-import { enableSpans, setTraceFilter } from "loggily"
-
-enableSpans() // All spans
-setTraceFilter(["myapp:db"]) // Only db spans
-```
-
-## Nested Spans
-
-Spans automatically track parent-child relationships and share trace IDs:
-
-```typescript
-{
-  using request = log.span("request", { path: "/api/users" })
-
-  {
-    using auth = request.span("auth")
-    await verifyToken()
-  }
-
-  {
-    using db = request.span("db:query")
-    // db.spanData.parentId === request.spanData.id
-    // db.spanData.traceId  === request.spanData.traceId
-    await fetchUsers()
-  }
-}
-```
-
-Output:
-
-```
-SPAN myapp:auth (12ms) {}
-SPAN myapp:db:query (45ms) {}
-SPAN myapp:request (62ms) {path: "/api/users"}
-```
-
-## Span Data
-
-Set custom attributes via `span.spanData`:
-
-```typescript
-{
-  using span = log.span("batch")
-  span.spanData.total = items.length
-
-  for (const item of items) {
-    await process(item)
-    span.spanData.processed = ((span.spanData.processed as number) ?? 0) + 1
-  }
-
-  span.spanData.status = "complete"
-}
-```
-
-### Read-only Properties
-
-| Property    | Type             | Description                          |
-| ----------- | ---------------- | ------------------------------------ |
-| `id`        | `string`         | Unique span ID (`sp_1`, `sp_2`, ...) |
-| `traceId`   | `string`         | Shared across nested spans           |
-| `parentId`  | `string \| null` | Parent span ID                       |
-| `startTime` | `number`         | Start timestamp (ms since epoch)     |
-| `endTime`   | `number \| null` | End timestamp (null while running)   |
-| `duration`  | `number`         | Live duration (computed on access)   |
-
-## Manual End
-
-For environments without `using` support:
-
-```typescript
-const span = log.span("operation")
-try {
-  await doWork()
-  span.spanData.result = "success"
-} finally {
-  span.end()
-}
-```
-
-## Logging Within Spans
-
-Spans are full loggers -- you can call `.info?.()`, `.debug?.()`, etc:
-
-```typescript
-{
-  using span = log.span("import")
-  span.info?.("starting import")
-  span.debug?.("reading file")
-  span.warn?.("skipping malformed row", { row: 42 })
-}
-```
-
-## JSON Output
-
-Spans respect the output format:
-
-```bash
-TRACE=1 LOG_FORMAT=json bun run app
-```
-
-```json
-{
-  "time": "2026-01-15T14:32:16.456Z",
-  "level": "span",
-  "name": "myapp:import",
-  "msg": "(1234ms)",
-  "duration": 1234,
-  "rowCount": 500
-}
-```

package/docs/site/guide/why.md

@@ -1,55 +0,0 @@
-# Why loggily?
-
-## The Problem
-
-Most loggers waste work when logging is disabled. Even when `debug` level is off:
-
-```typescript
-// Pino, Winston, Bunyan
-log.debug(`state: ${JSON.stringify(computeExpensiveState())}`)
-```
-
-`computeExpensiveState()` runs, `JSON.stringify()` runs, the string is concatenated -- all discarded because debug is off. In hot code paths (rendering loops, per-node operations), this adds up.
-
-## The Solution
-
-loggily uses optional chaining to skip argument evaluation entirely:
-
-```typescript
-log.debug?.(`state: ${JSON.stringify(computeExpensiveState())}`)
-```
-
-When `debug` is disabled, `log.debug` is `undefined`. JavaScript's `?.` operator short-circuits: `computeExpensiveState()` never runs, `JSON.stringify()` never runs, the string is never built.
-
-## Benchmarks
-
-10M iterations, Bun 1.1.x, M1 Mac:
-
-| Scenario                               | ops/s    | ns/op   |
-| -------------------------------------- | -------- | ------- |
-| Traditional noop (cheap args)          | 2168M    | 0.5     |
-| Optional chaining (cheap args)         | 1406M    | 0.7     |
-| Traditional noop (expensive args)      | 17M      | 57.6    |
-| **Optional chaining (expensive args)** | **408M** | **2.5** |
-
-For cheap arguments the overhead is ~0.2ns -- negligible. For expensive arguments, **22x faster**.
-
-## Compared to Others
-
-| Feature            | loggily    | Pino  | Winston | debug |
-| ------------------ | ---------- | ----- | ------- | ----- |
-| Zero-cost disabled | `?.` (22x) | noop  | noop    | check |
-| Built-in spans     | Yes        | No    | No      | No    |
-| Bundle size        | ~3KB       | ~17KB | ~200KB+ | ~2KB  |
-| TypeScript native  | Yes        | Types | Types   | Types |
-| Worker threads     | Yes        | No    | No      | No    |
-
-See [Comparison](https://github.com/beorn/loggily/blob/main/docs/comparison.md) for detailed analysis of each.
-
-## Design Principles
-
-1. **Logger = Span**: Every logger can become a span. No separate tracing library needed.
-2. **Zero cost**: Disabled levels skip everything, including argument evaluation.
-3. **Minimal surface**: Few functions, each does one thing well.
-4. **Type enforced**: TypeScript makes `?.` mandatory -- you can't accidentally call a disabled level.
-5. **Structured**: JSON in production, readable console in development.

package/docs/site/guide/workers.md

@@ -1,113 +0,0 @@
-# Worker Thread Support
-
-loggily provides typed message protocols for forwarding logs from worker threads to the main thread.
-
-## Full Logger Forwarding
-
-### Worker Side
-
-```typescript
-import { createWorkerLogger } from "loggily/worker"
-
-const log = createWorkerLogger(postMessage, "myapp:worker")
-
-log.info?.("processing", { file: "data.csv" })
-
-{
-  using span = log.span("parse")
-  span.info?.("parsing rows")
-  span.spanData.lines = 100
-}
-// Span events forwarded to main thread automatically
-```
-
-### Main Thread Side
-
-```typescript
-import { createWorkerLogHandler, isWorkerMessage } from "loggily/worker"
-
-const handle = createWorkerLogHandler()
-
-worker.onmessage = (e) => {
-  if (isWorkerMessage(e.data)) {
-    handle(e.data)
-  } else {
-    // Handle other message types
-  }
-}
-```
-
-## Console Forwarding
-
-For simpler cases, forward `console.*` calls:
-
-### Worker Side
-
-```typescript
-import { forwardConsole } from "loggily/worker"
-
-forwardConsole(postMessage, "myapp:worker")
-
-// All console.* calls are now forwarded
-console.log("processing", { file: "data.csv" })
-console.error(new Error("failed"))
-```
-
-### Main Thread Side
-
-```typescript
-import { createWorkerConsoleHandler } from "loggily/worker"
-
-const handle = createWorkerConsoleHandler({
-  defaultNamespace: "myapp:worker",
-})
-
-worker.onmessage = (e) => {
-  if (e.data.type === "console") {
-    handle(e.data)
-  }
-}
-```
-
-## Message Types
-
-All messages are fully typed. Use the type guards to safely handle them:
-
-```typescript
-import {
-  isWorkerConsoleMessage,
-  isWorkerLogMessage,
-  isWorkerSpanMessage,
-  isWorkerMessage,
-  type WorkerMessage,
-} from "loggily/worker"
-```
-
-| Type Guard               | Message Type            |
-| ------------------------ | ----------------------- |
-| `isWorkerConsoleMessage` | `console.*` forwarding  |
-| `isWorkerLogMessage`     | Structured log messages |
-| `isWorkerSpanMessage`    | Span start/end events   |
-| `isWorkerMessage`        | Any of the above        |
-
-## Serialization
-
-Arguments are automatically serialized for `postMessage`:
-
-- Functions become `"[Function: name]"`
-- Symbols become their `toString()` representation
-- BigInts become `"123n"` strings
-- Circular references become `"[Circular]"`
-- Errors become `{ name, message, stack }` objects
-- Depth is capped at 5 levels
-
-## Restoring Console
-
-If you need to disable console forwarding:
-
-```typescript
-import { restoreConsole } from "loggily/worker"
-
-// Later:
-restoreConsole() // Original console methods restored
-```

package/docs/site/guide/zero-overhead.md

@@ -1,87 +0,0 @@
-# Zero-Overhead Logging
-
-## How It Works
-
-`createLogger()` returns a `ConditionalLogger` -- a Proxy where disabled log levels return `undefined`:
-
-```typescript
-const log = createLogger("myapp")
-
-// At default level (info):
-typeof log.trace // undefined
-typeof log.debug // undefined
-typeof log.info // function
-typeof log.warn // function
-typeof log.error // function
-```
-
-Using `?.` means the entire call is skipped when the method is undefined:
-
-```typescript
-log.debug?.(`tree: ${JSON.stringify(buildTree())}`)
-// buildTree() and JSON.stringify() NEVER run when debug is off
-```
-
-## Lazy Messages
-
-For even more control, pass a function:
-
-```typescript
-log.debug?.(() => {
-  const state = gatherComplexState()
-  return `state: ${JSON.stringify(state)}`
-})
-// Function only called when debug is enabled
-```
-
-Type: `LazyMessage = string | (() => string)`
-
-Both patterns work with all log levels and with structured data:
-
-```typescript
-log.trace?.(() => `verbose: ${expensiveComputation()}`, { extra: "data" })
-```
-
-## Dynamic Levels
-
-The logger responds to level changes in real-time:
-
-```typescript
-import { createLogger, setLogLevel } from "loggily"
-
-const log = createLogger("myapp")
-
-setLogLevel("error")
-log.debug // undefined
-log.info // undefined
-
-setLogLevel("debug")
-log.debug // function (now available)
-log.info // function
-```
-
-## TypeScript Enforcement
-
-TypeScript's type system makes `?.` mandatory:
-
-```typescript
-const log = createLogger("myapp")
-
-log.debug("msg") // Type error: Object is possibly 'undefined'
-log.debug?.("msg") // Correct
-```
-
-## Performance Numbers
-
-10M iterations, Bun 1.1.x, M1 Mac:
-
-| Pattern           | Cheap args | Expensive args |
-| ----------------- | ---------- | -------------- |
-| Noop function     | 0.5 ns/op  | 57.6 ns/op     |
-| Optional chaining | 0.7 ns/op  | **2.5 ns/op**  |
-| Proxy + noop      | 2.8 ns/op  | 65.3 ns/op     |
-| Proxy + `?.`      | 1.8 ns/op  | 5.9 ns/op      |
-
-The Proxy overhead (~1ns) comes from `createLogger()` wrapping the base logger. For logging operations this is negligible compared to the actual I/O.
-
-See [Conditional Logging Research](https://github.com/beorn/loggily/blob/main/docs/conditional-logging-research.md) for methodology and external references.

package/docs/site/index.md

@@ -1,54 +0,0 @@
----
-layout: home
-
-hero:
-  name: "loggily"
-  text: "Clarity without the clutter"
-  tagline: "Debug logging, structured logs, and distributed tracing — integrated into one ~3KB library. Zero dependencies, zero-overhead via optional chaining."
-  actions:
-    - theme: brand
-      text: The Journey
-      link: /guide/journey
-    - theme: alt
-      text: View on GitHub
-      link: https://github.com/beorn/loggily
-
-features:
-  - title: "Debug Logging"
-    details: "Namespace filtering with DEBUG=myapp,-myapp:noisy — same ergonomics as the debug package. Uses native console methods so source lines stay clickable in DevTools."
-  - title: "Structured Logs"
-    details: "Colorized console with timestamps and clickable source lines in development. Structured JSON in production. Same code, same API — output format switches automatically."
-  - title: "Distributed Tracing"
-    details: "Built-in spans with automatic timing, parent-child tracking, trace IDs, and traceparent headers. All integrated — no separate SDK to wire up."
-  - title: Zero-Overhead via ?.
-    details: "Optional chaining skips the entire call — including argument evaluation — when a level is disabled. Typically 10x+ faster for real-world logging with string interpolation and serialization."
-  - title: ~3KB, Zero Dependencies
-    details: "No external dependencies. Native TypeScript, ESM-only. Runs on Node, Bun, and Deno."
-  - title: One Unified Pipeline
-    details: "Most projects wire together debug, pino, and OpenTelemetry — three configs, three formats, three APIs. loggily integrates all three: one namespace tree, one output pipeline, one import instead of three."
----
-
-## Quick Start
-
-```bash
-bun add loggily
-```
-
-```typescript
-import { createLogger } from "loggily"
-
-const log = createLogger("myapp")
-
-// ?. skips the entire call — including argument evaluation — when the level is disabled (near-zero cost)
-log.info?.("server started", { port: 3000 })
-log.debug?.("cache hit", { key: "user:42" })
-log.error?.(new Error("connection lost"))
-
-// Spans time operations automatically
-{
-  using span = log.span("db:query", { table: "users" })
-  const users = await db.query("SELECT * FROM users")
-  span.spanData.count = users.length
-}
-// Output: SPAN myapp:db:query (45ms) {count: 100, table: "users"}
-```