loggily 0.3.0 → 0.4.1

package/docs/site/.vitepress/config.ts

@@ -1,67 +0,0 @@
-import { defineConfig } from "vitepress"
-
-export default defineConfig({
-  title: "loggily",
-  description: "Clarity without the clutter. Ergonomic unified logs, spans, and debugs for modern TypeScript.",
-  base: "/loggily/",
-
-  themeConfig: {
-    siteTitle: "loggily",
-
-    nav: [
-      { text: "Guide", link: "/guide/journey" },
-      { text: "API", link: "/api/" },
-      { text: "GitHub", link: "https://github.com/beorn/loggily" },
-    ],
-
-    sidebar: {
-      "/guide/": [
-        {
-          text: "Introduction",
-          items: [
-            { text: "The Journey", link: "/guide/journey" },
-            { text: "Getting Started", link: "/guide/getting-started" },
-            { text: "Why loggily?", link: "/guide/why" },
-          ],
-        },
-        {
-          text: "Features",
-          items: [
-            { text: "Zero-Overhead Logging", link: "/guide/zero-overhead" },
-            { text: "Spans", link: "/guide/spans" },
-            { text: "Worker Threads", link: "/guide/workers" },
-          ],
-        },
-        {
-          text: "Migration",
-          items: [{ text: "From debug", link: "/guide/migration-from-debug" }],
-        },
-      ],
-      "/api/": [
-        {
-          text: "API Reference",
-          items: [
-            { text: "Overview", link: "/api/" },
-            { text: "Logger", link: "/api/logger" },
-            { text: "Configuration", link: "/api/configuration" },
-            { text: "Writers", link: "/api/writers" },
-            { text: "Worker Thread", link: "/api/worker" },
-          ],
-        },
-      ],
-    },
-
-    socialLinks: [{ icon: "github", link: "https://github.com/beorn/loggily" }],
-
-    outline: { level: [2, 3] },
-
-    search: {
-      provider: "local",
-    },
-
-    footer: {
-      message: "Released under the MIT License.",
-      copyright: "Copyright © 2026 Bjørn Stabell",
-    },
-  },
-})

package/docs/site/api/configuration.md

@@ -1,94 +0,0 @@
-# Configuration
-
-## Log Level
-
-```typescript
-setLogLevel(level: LogLevel): void
-getLogLevel(): LogLevel
-```
-
-Default: `"info"`. Override with `LOG_LEVEL` env var.
-
-```typescript
-setLogLevel("debug") // debug, info, warn, error
-setLogLevel("error") // error only
-setLogLevel("silent") // nothing
-```
-
-## Log Format
-
-```typescript
-setLogFormat(format: LogFormat): void
-getLogFormat(): LogFormat
-```
-
-Default: `"console"`. Override with `LOG_FORMAT` env var. Also auto-enabled by `NODE_ENV=production`.
-
-```typescript
-setLogFormat("json") // {"time":"...","level":"info","name":"myapp","msg":"..."}
-setLogFormat("console") // 14:32:15 INFO myapp message
-```
-
-## Span Control
-
-```typescript
-enableSpans(): void
-disableSpans(): void
-spansAreEnabled(): boolean
-```
-
-## Trace Filter
-
-```typescript
-setTraceFilter(namespaces: string[] | null): void
-getTraceFilter(): string[] | null
-```
-
-Only emit spans matching these namespace prefixes.
-
-```typescript
-setTraceFilter(["myapp:db"]) // Only db spans
-setTraceFilter(null) // All spans
-```
-
-## Debug Filter
-
-```typescript
-setDebugFilter(namespaces: string[] | null): void
-getDebugFilter(): string[] | null
-```
-
-Filter log output by namespace. Supports negative patterns.
-
-```typescript
-setDebugFilter(["myapp"]) // Only myapp and children
-setDebugFilter(["myapp", "-myapp:sql"]) // Exclude sql
-setDebugFilter(null) // All namespaces
-```
-
-Auto-lowers log level to `debug` when set.
-
-## Output Mode
-
-```typescript
-setOutputMode(mode: OutputMode): void
-getOutputMode(): OutputMode
-setSuppressConsole(value: boolean): void
-```
-
-| Mode             | Console | Writers |
-| ---------------- | ------- | ------- |
-| `"console"`      | Yes     | Yes     |
-| `"stderr"`       | stderr  | Yes     |
-| `"writers-only"` | No      | Yes     |
-
-## Environment Variables
-
-| Variable       | Values                                  | Default   |
-| -------------- | --------------------------------------- | --------- |
-| `LOG_LEVEL`    | trace, debug, info, warn, error, silent | `info`    |
-| `LOG_FORMAT`   | console, json                           | `console` |
-| `DEBUG`        | `*`, namespace prefixes, `-prefix`      | (none)    |
-| `TRACE`        | `1`, `true`, namespace prefixes         | (none)    |
-| `TRACE_FORMAT` | json                                    | (none)    |
-| `NODE_ENV`     | production                              | (none)    |

package/docs/site/api/index.md

@@ -1,61 +0,0 @@
-# API Reference
-
-See the [full API reference](https://github.com/beorn/loggily/blob/main/docs/api-reference.md) for complete documentation.
-
-## Exports from `loggily`
-
-### Core
-
-| Export                                                   | Description                              |
-| -------------------------------------------------------- | ---------------------------------------- |
-| `createLogger(name, props?)`                             | Create a conditional logger              |
-| `setLogLevel(level)` / `getLogLevel()`                   | Log level control                        |
-| `setLogFormat(format)` / `getLogFormat()`                | Output format (`"console"` or `"json"`)  |
-| `enableSpans()` / `disableSpans()` / `spansAreEnabled()` | Span output control                      |
-| `setTraceFilter(ns)` / `getTraceFilter()`                | Namespace-based span filtering           |
-| `setDebugFilter(ns)` / `getDebugFilter()`                | Namespace-based log filtering            |
-| `setOutputMode(mode)` / `getOutputMode()`                | Output destination                       |
-| `setSuppressConsole(bool)`                               | Suppress console (writers still receive) |
-
-### Writers
-
-| Export                          | Description                       |
-| ------------------------------- | --------------------------------- |
-| `addWriter(fn)`                 | Subscribe to all formatted output |
-| `createFileWriter(path, opts?)` | Buffered file writer              |
-
-### Testing
-
-| Export                                          | Description                    |
-| ----------------------------------------------- | ------------------------------ |
-| `startCollecting()` / `stopCollecting()`        | Collect span data for analysis |
-| `getCollectedSpans()` / `clearCollectedSpans()` | Access collected spans         |
-| `resetIds()`                                    | Reset span/trace ID counters   |
-
-### Types
-
-| Export              | Description                               |
-| ------------------- | ----------------------------------------- |
-| `Logger`            | Full logger interface                     |
-| `SpanLogger`        | Logger + Disposable + SpanData            |
-| `ConditionalLogger` | Logger with optional methods              |
-| `SpanData`          | Span timing and attributes                |
-| `LogLevel`          | `"trace" \| "debug" \| ... \| "silent"`   |
-| `LogFormat`         | `"console" \| "json"`                     |
-| `LazyMessage`       | `string \| (() => string)`                |
-| `OutputMode`        | `"console" \| "stderr" \| "writers-only"` |
-| `FileWriter`        | `{ write, flush, close }`                 |
-
-## Exports from `loggily/worker`
-
-| Export                                        | Description                       |
-| --------------------------------------------- | --------------------------------- |
-| `createWorkerLogger(postMessage, ns, props?)` | Logger for worker threads         |
-| `createWorkerLogHandler(opts?)`               | Main thread handler               |
-| `createWorkerConsoleHandler(opts?)`           | Console message handler           |
-| `forwardConsole(postMessage, ns?)`            | Forward console.\* from worker    |
-| `restoreConsole()`                            | Restore original console methods  |
-| `isWorkerMessage(msg)`                        | Type guard for any worker message |
-| `isWorkerConsoleMessage(msg)`                 | Type guard for console messages   |
-| `isWorkerLogMessage(msg)`                     | Type guard for log messages       |
-| `isWorkerSpanMessage(msg)`                    | Type guard for span messages      |

package/docs/site/api/logger.md

@@ -1,99 +0,0 @@
-# Logger
-
-## createLogger
-
-```typescript
-function createLogger(name: string, props?: Record<string, unknown>): ConditionalLogger
-```
-
-Create a conditional logger. Disabled log levels return `undefined` -- use `?.` for zero-overhead.
-
-```typescript
-const log = createLogger("myapp", { version: "2.1" })
-log.info?.("started")
-```
-
-## Logger Methods
-
-### Logging
-
-All accept `LazyMessage` (string or `() => string`) and optional data:
-
-```typescript
-log.trace?.("verbose", { detail: "..." })
-log.debug?.("debugging", { state: "..." })
-log.info?.("normal operation")
-log.warn?.("recoverable issue")
-log.error?.(new Error("failed"))
-log.error?.("manual error", { code: "ETIMEOUT" })
-```
-
-### Child Creation
-
-```typescript
-// Extend namespace, inherit props
-const db = log.logger("db", { pool: "primary" })
-// namespace: "myapp:db", props: { version: "2.1", pool: "primary" }
-
-// Add context to every message (same namespace)
-const req = log.child({ requestId: "abc" })
-
-// Create timed span
-{
-  using span = log.span("import")
-  span.spanData.count = 42
-}
-```
-
-### Manual Span End
-
-```typescript
-const span = log.span("op")
-try {
-  /* ... */
-} finally {
-  span.end()
-}
-```
-
-## ConditionalLogger
-
-The return type of `createLogger()`. Log methods are possibly `undefined`:
-
-```typescript
-interface ConditionalLogger {
-  readonly name: string
-  readonly props: Readonly<Record<string, unknown>>
-  trace?: (msg: LazyMessage, data?: Record<string, unknown>) => void
-  debug?: (msg: LazyMessage, data?: Record<string, unknown>) => void
-  info?: (msg: LazyMessage, data?: Record<string, unknown>) => void
-  warn?: (msg: LazyMessage, data?: Record<string, unknown>) => void
-  error?: (msg: LazyMessage | Error, data?: Record<string, unknown>) => void
-  logger(ns?: string, props?: Record<string, unknown>): Logger
-  span(ns?: string, props?: Record<string, unknown>): SpanLogger
-  child(context: Record<string, unknown>): Logger
-  end(): void
-}
-```
-
-## SpanLogger
-
-Logger + timing + Disposable:
-
-```typescript
-interface SpanLogger extends Logger, Disposable {
-  readonly spanData: SpanData & { [key: string]: unknown }
-}
-```
-
-### SpanData
-
-| Property    | Type             | Writable | Description                 |
-| ----------- | ---------------- | -------- | --------------------------- |
-| `id`        | `string`         | No       | `sp_1`, `sp_2`, ...         |
-| `traceId`   | `string`         | No       | Shared across nested spans  |
-| `parentId`  | `string \| null` | No       | Parent span ID              |
-| `startTime` | `number`         | No       | Start timestamp             |
-| `endTime`   | `number \| null` | No       | End timestamp               |
-| `duration`  | `number`         | No       | Live computed duration      |
-| `[custom]`  | `unknown`        | **Yes**  | `span.spanData.key = value` |

package/docs/site/api/worker.md

@@ -1,120 +0,0 @@
-# Worker Thread API
-
-Import from `loggily/worker`.
-
-## Worker Side
-
-### createWorkerLogger
-
-```typescript
-function createWorkerLogger(
-  postMessage: (msg: WorkerMessage) => void,
-  namespace: string,
-  props?: Record<string, unknown>,
-  options?: { parentSpanId?: string; traceId?: string },
-): Logger
-```
-
-Create a logger that forwards all output to the main thread via `postMessage`.
-
-```typescript
-const log = createWorkerLogger(postMessage, "myapp:worker")
-log.info?.("processing", { file: "data.csv" })
-
-{
-  using span = log.span("parse")
-  span.spanData.lines = 100
-}
-```
-
-### forwardConsole
-
-```typescript
-function forwardConsole(postMessage: (msg: WorkerConsoleMessage) => void, namespace?: string): void
-```
-
-Monkey-patch `console.*` to forward output via `postMessage`.
-
-```typescript
-forwardConsole(postMessage, "myapp:worker")
-console.log("this is forwarded")
-```
-
-### restoreConsole
-
-```typescript
-function restoreConsole(): void
-```
-
-Restore original `console.*` methods.
-
-## Main Thread Side
-
-### createWorkerLogHandler
-
-```typescript
-function createWorkerLogHandler(options?: { enableSpans?: boolean }): (message: WorkerMessage) => void
-```
-
-Handle all worker messages (logs, spans, console). Creates loggers per namespace automatically.
-
-```typescript
-const handle = createWorkerLogHandler({ enableSpans: true })
-worker.onmessage = (e) => handle(e.data)
-```
-
-### createWorkerConsoleHandler
-
-```typescript
-function createWorkerConsoleHandler(options?: {
-  defaultNamespace?: string
-  logger?: Logger
-}): (message: WorkerConsoleMessage) => void
-```
-
-Handle only console forwarding messages.
-
-## Type Guards
-
-```typescript
-isWorkerMessage(msg: unknown): msg is WorkerMessage
-isWorkerConsoleMessage(msg: unknown): msg is WorkerConsoleMessage
-isWorkerLogMessage(msg: unknown): msg is WorkerLogMessage
-isWorkerSpanMessage(msg: unknown): msg is WorkerSpanMessage
-```
-
-## Message Types
-
-```typescript
-interface WorkerConsoleMessage {
-  type: "console"
-  level: "log" | "debug" | "info" | "warn" | "error" | "trace"
-  namespace?: string
-  args: unknown[]
-  timestamp: number
-}
-
-interface WorkerLogMessage {
-  type: "log"
-  level: "trace" | "debug" | "info" | "warn" | "error"
-  namespace: string
-  message: string
-  data?: Record<string, unknown>
-  timestamp: number
-}
-
-interface WorkerSpanMessage {
-  type: "span"
-  event: "start" | "end"
-  namespace: string
-  spanId: string
-  traceId: string
-  parentId: string | null
-  startTime: number
-  endTime?: number
-  duration?: number
-  props: Record<string, unknown>
-  spanData: Record<string, unknown>
-  timestamp: number
-}
-```

package/docs/site/api/writers.md

@@ -1,69 +0,0 @@
-# Writers
-
-## addWriter
-
-```typescript
-function addWriter(writer: (formatted: string, level: string) => void): () => void
-```
-
-Subscribe to all formatted log output. Returns an unsubscribe function.
-
-```typescript
-const lines: string[] = []
-const unsub = addWriter((formatted, level) => {
-  lines.push(formatted)
-})
-
-// Later:
-unsub()
-```
-
-Writers receive output regardless of `setOutputMode()` or `setSuppressConsole()` settings.
-
-## createFileWriter
-
-```typescript
-function createFileWriter(path: string, options?: FileWriterOptions): FileWriter
-```
-
-Create a buffered file writer that flushes automatically.
-
-### Options
-
-| Option          | Type     | Default | Description                            |
-| --------------- | -------- | ------- | -------------------------------------- |
-| `bufferSize`    | `number` | 4096    | Flush when buffer exceeds this (bytes) |
-| `flushInterval` | `number` | 100     | Flush every N milliseconds             |
-
-### FileWriter Methods
-
-| Method        | Description                           |
-| ------------- | ------------------------------------- |
-| `write(line)` | Append line to buffer (adds `\n`)     |
-| `flush()`     | Write buffer to disk immediately      |
-| `close()`     | Flush remaining buffer and close file |
-
-### Example
-
-```typescript
-import { createFileWriter, addWriter } from "loggily"
-
-const writer = createFileWriter("/tmp/app.log", {
-  bufferSize: 8192,
-  flushInterval: 200,
-})
-
-const unsub = addWriter((formatted) => writer.write(formatted))
-
-// On shutdown:
-unsub()
-writer.close()
-```
-
-### Safety
-
-- The flush interval timer is `unref()`'d so it won't keep the process alive
-- A `process.on("exit")` handler flushes remaining buffer on shutdown
-- `close()` removes the exit handler and clears the interval
-- Multiple `close()` calls are safe (idempotent)
-- `write()` after `close()` is silently ignored

package/docs/site/guide/getting-started.md

@@ -1,143 +0,0 @@
-# Getting Started
-
-## Installation
-
-```bash
-bun add loggily    # or: npm install loggily
-```
-
-## Create a Logger
-
-```typescript
-import { createLogger } from "loggily"
-
-const log = createLogger("myapp")
-```
-
-The string argument is the **namespace** -- it appears in every log message and is used for filtering.
-
-## Log Messages
-
-Every log method accepts a message string and optional structured data:
-
-```typescript
-log.info?.("server started", { port: 3000 })
-log.debug?.("cache hit", { key: "user:42", ttl: 300 })
-log.warn?.("rate limited", { remaining: 0, resetIn: 60 })
-log.error?.(new Error("connection lost"))
-```
-
-Notice the `?.` -- this is intentional. When a log level is disabled, the method returns `undefined`, and optional chaining skips the entire call including argument evaluation. This is the core performance feature of loggily.
-
-## Log Levels
-
-From most to least verbose:
-
-| Level    | Purpose               | Default |
-| -------- | --------------------- | ------- |
-| `trace`  | Hot path debugging    | Off     |
-| `debug`  | Development debugging | Off     |
-| `info`   | Normal operation      | **On**  |
-| `warn`   | Recoverable issues    | On      |
-| `error`  | Failures              | On      |
-| `silent` | Disable all output    | --      |
-
-Control via environment variable or programmatically:
-
-```bash
-LOG_LEVEL=debug bun run app     # Enable debug and above
-LOG_LEVEL=error bun run app     # Only errors
-```
-
-```typescript
-import { setLogLevel } from "loggily"
-setLogLevel("debug")
-```
-
-## Child Loggers
-
-Build a namespace hierarchy with `.logger()`:
-
-```typescript
-const log = createLogger("myapp")
-const db = log.logger("db") // namespace: "myapp:db"
-const cache = log.logger("cache") // namespace: "myapp:cache"
-
-db.info?.("connected", { host: "localhost" })
-// 14:32:15 INFO myapp:db connected {host: "localhost"}
-```
-
-Props are inherited by children:
-
-```typescript
-const log = createLogger("myapp", { version: "2.1" })
-const db = log.logger("db")
-// db.props includes { version: "2.1" }
-```
-
-## Context Loggers
-
-Add structured context that appears in every message:
-
-```typescript
-const reqLog = log.child({ requestId: "abc-123" })
-reqLog.info?.("handling request")
-// 14:32:15 INFO myapp handling request {requestId: "abc-123"}
-```
-
-## Spans
-
-Time any operation with `using`:
-
-```typescript
-{
-  using span = log.span("import", { file: "data.csv" })
-  span.info?.("parsing")
-  const rows = await importFile()
-  span.spanData.rowCount = rows.length
-}
-// SPAN myapp:import (1234ms) {rowCount: 500, file: "data.csv"}
-```
-
-Spans are disabled by default. Enable with:
-
-```bash
-TRACE=1 bun run app              # All spans
-TRACE=myapp:import bun run app   # Specific namespace
-```
-
-See [Spans](/guide/spans) for the full guide.
-
-## Namespace Filtering
-
-Filter output by namespace, just like the `debug` package:
-
-```bash
-DEBUG=myapp bun run app                  # Only myapp and children
-DEBUG='myapp,-myapp:noisy' bun run app   # Exclude noisy sub-namespace
-DEBUG='*' bun run app                    # Everything
-```
-
-## Output Format
-
-Pretty console in development, JSON in production:
-
-```bash
-# Development (default)
-bun run app
-# 14:32:15 INFO myapp server started {port: 3000}
-
-# Production (automatic)
-NODE_ENV=production bun run app
-# {"time":"2026-01-15T14:32:15.123Z","level":"info","name":"myapp","msg":"server started","port":3000}
-
-# Explicit
-LOG_FORMAT=json bun run app
-```
-
-## Next Steps
-
-- [Zero-Overhead Logging](/guide/zero-overhead) -- How optional chaining works and benchmarks
-- [Spans](/guide/spans) -- Timing, nesting, trace IDs
-- [Worker Threads](/guide/workers) -- Forward logs from workers
-- [API Reference](/api/) -- Complete API documentation