loggily 0.0.1 → 0.3.0

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

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

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

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

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

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

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

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