loggily 0.6.0 → 0.6.2

package/README.md

@@ -2,42 +2,28 @@
 
 **Clarity without the clutter.**
 
-One library. One namespace tree. One output pipeline. For logs (structured JSON or console), debug(), and tracing spans. Near-zero overhead from disabled log levels. Pure TypeScript. ~3KB. Zero dependencies.
+Debugs, logs, and spans — one API.
 
 [![Tests](https://github.com/beorn/loggily/actions/workflows/test.yml/badge.svg)](https://github.com/beorn/loggily/actions/workflows/test.yml)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.2+-blue.svg)](https://www.typescriptlang.org/)
+[![npm version](https://img.shields.io/npm/v/loggily.svg)](https://www.npmjs.com/package/loggily)
+[![size](https://img.shields.io/bundlephobia/minzip/loggily)](https://bundlephobia.com/package/loggily)
 [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-> Early release (0.x) -- API may evolve before 1.0.
+Most apps end up with three logging tools: `debug` for local troubleshooting, a JSON logger like Pino for production, and ad-hoc timers or a tracing SDK for performance. Three APIs, three configs, three output formats.
 
-## Install
-
-```bash
-npm install loggily
-```
-
-| Requirement   | Version                                           |
-| ------------- | ------------------------------------------------- |
-| Node.js       | >= 23.6                                           |
-| Bun           | 1.0+                                              |
-| TypeScript    | 5.2+ (for `using`; `.end()` works on any version) |
-| Module format | ESM-only                                          |
-| Browser       | Supported via conditional export                  |
-
-## Quick Start
+Loggily replaces all three with one namespace tree and one output pipeline. Pure TypeScript, zero dependencies, ~3 KB.
 
 ```typescript
 import { createLogger } from "loggily"
 
 const log = createLogger("myapp")
 
-// ?. skips the entire call — including argument evaluation — when the level is disabled
 log.info?.("server started", { port: 3000 })
 log.debug?.("cache hit", { key: "user:42" })
 log.error?.(new Error("connection lost"))
 ```
 
-Output in development (colorized with timestamps and clickable source lines):
+Readable, colorized output in development:
 
 ```
 14:32:15 INFO myapp server started {port: 3000}
@@ -45,75 +31,95 @@ Output in development (colorized with timestamps and clickable source lines):
 14:32:15 ERROR myapp connection lost
 ```
 
-Set `NODE_ENV=production` or `LOG_FORMAT=json` and the same code emits structured JSON:
+Set `NODE_ENV=production` and the same calls emit structured JSON:
 
 ```json
 { "time": "2024-01-15T14:32:15.123Z", "level": "info", "name": "myapp", "msg": "server started", "port": 3000 }
 ```
 
-### Spans
+## Why the `?.`
 
-Time operations with lightweight spans. Uses TC39 [Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management) (`using` requires TypeScript 5.2+ and runtime support). For other environments, call `.end()` manually:
+Disabled logs should not build strings, serialize objects, or compute snapshots just to throw them away.
 
-```typescript
-// With `using` (TS 5.2+, Bun 1.0+, Node 22+)
-{
-  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"}
+With most loggers, this work still happens:
 
-// Without `using` — works on any runtime
-const span = log.span("db:query", { table: "users" })
-try {
-  const users = await db.query("SELECT * FROM users")
-  span.spanData.count = users.length
-} finally {
-  span.end()
-}
+```typescript
+log.debug(`state: ${JSON.stringify(computeExpensiveState())}`)
+// computeExpensiveState() runs even when debug is off
 ```
 
-## Why Loggily?
+With Loggily, optional chaining short-circuits the entire call:
 
-One API for debug-style namespace logging, structured JSON output, and lightweight spans. Many projects end up with separate tools for these -- **debug** for conditional output, **pino/winston** for production logs, a tracing SDK for timings -- with separate configs, formats, and APIs. Loggily integrates all three into one namespace tree, one output pipeline, one `?.` pattern.
+```typescript
+log.debug?.(`state: ${JSON.stringify(computeExpensiveState())}`)
+// nothing runs when debug is off — not the function, not the stringify, not the template
+```
 
-### Near-zero cost for disabled logs
+In benchmarks with expensive disabled log arguments, this is [~22x faster](https://beorn.codes/loggily/guide/benchmarks) than a conventional noop logger.
 
-Most loggers waste work when logging is disabled. Even with a noop function, arguments are still evaluated:
+## Install
 
-```typescript
-// Traditional — args are ALWAYS evaluated, even when debug is off
-log.debug(`state: ${JSON.stringify(computeExpensiveState())}`)
+```bash
+npm install loggily
 ```
 
-Loggily uses optional chaining to skip the entire call — including argument evaluation:
+| Requirement | Version |
+|---|---|
+| Node.js | >= 23.6 |
+| Bun | 1.0+ |
+| TypeScript | 5.2+ for `using`; `.end()` works on any version |
+| Module format | ESM-only |
+| Browser | Supported via conditional export |
+
+Loggily uses `Symbol.dispose` (TC39 Explicit Resource Management) for span cleanup, which requires a modern runtime.
+
+## Features
+
+- **Namespace hierarchy** — organize logs with `:` separators. `DEBUG=myapp:db` shows only database output, just like the `debug` package.
+- **Lightweight spans** — time any operation with `using span = log.span("name")`. Automatic duration, parent-child tracking, and trace IDs.
+- **Dev & production** — colorized console in development, structured JSON in production. Same code, zero config.
+- **Child context** — `log.child({ requestId })` adds structured fields to every message in the chain.
+- **Automatic async context** — enable `AsyncLocalStorage`-based propagation and every log in a request's async chain inherits trace/span IDs without passing loggers around.
+- **Lazy messages** — `log.debug?.(() => expensiveString())` skips the function entirely when disabled.
+- **File writer** — `addWriter()` + `createFileWriter()` for buffered file output.
+- **Worker threads** — forward logs from workers to the main thread with full type safety.
+
+### Spans
 
 ```typescript
-// Loggily — args are NOT evaluated when disabled
-log.debug?.(`state: ${JSON.stringify(computeExpensiveState())}`)
+{
+  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"}
+
+// Without `using` — call .end() manually
+const span = log.span("db:query")
+try { /* ... */ } finally { span.end() }
 ```
 
-For trivial arguments the difference is negligible. But for real-world logging — string interpolation, JSON serialization, state snapshots — optional chaining is typically **10x+ faster** because it skips the work entirely. The more expensive your arguments, the bigger the win.
+### Common configuration
 
-> **Note**: The big performance advantage is specifically for disabled logging with expensive arguments, not universal logger throughput. Pino is optimized for high-throughput enabled JSON logging; Loggily's biggest advantage is skipping work when logs are disabled. See [benchmarks](https://beorn.codes/loggily/guide/benchmarks) for detailed numbers per scenario.
+| Variable | Example | Effect |
+|---|---|---|
+| `DEBUG` | `myapp:db,-myapp:sql` | Namespace filter (same syntax as the `debug` package) |
+| `LOG_LEVEL` | `debug`, `info`, `warn` | Minimum output level |
+| `LOG_FORMAT` | `console`, `json` | Override output format |
+| `TRACE` | `1` or namespace prefixes | Enable span output |
 
-## Features
+See the [full environment variable reference](https://beorn.codes/loggily/api/configuration).
 
-- **Namespace hierarchy** — organize logs with `:` separators. `log.logger("db")` creates `myapp:db`. Children inherit parent context.
-- **Lightweight spans and trace IDs** — time any operation with `using span = log.span("name")`. Automatic duration, parent-child tracking, and trace IDs. For full OpenTelemetry interoperability with exporters and propagation, use OpenTelemetry.
-- **Lazy messages** — `log.debug?.(() => expensiveString())` skips the function entirely when disabled.
-- **Child context** — `log.child({ requestId })` adds structured fields to every message in the chain.
-- **Dev & production** — colorized console with timestamps, level colors, and clickable source lines in development. Structured JSON in production. Switches automatically via `NODE_ENV` — same code, zero config.
-- **File writer** — `addWriter()` + `createFileWriter()` for buffered file output with auto-flush.
-- **Worker threads** — forward logs from workers to the main thread with full type safety (`loggily/worker`).
-- **debug-compatible namespace filtering** — reads `DEBUG=myapp:*` just like the debug package. Easy migration from debug — see the [migration guide](https://beorn.codes/loggily/guide/migration-from-debug).
+## Why this exists
 
-## When Not to Use Loggily
+Loggily was built while developing a terminal UI where disabled debug logs inside the render loop were eating frame time. No existing logger solved the "disabled calls should cost nothing" problem at the language level, so `?.` became the foundation.
 
-- **Max-throughput transport pipelines** — use [Pino](https://getpino.io/) for worker-thread transports, custom serializers, and log rotation.
-- **Vendor/exporter interop** — use [OpenTelemetry](https://opentelemetry.io/) for distributed tracing with propagation, semantic conventions, and backend integrations.
-- **Tiny dev-only namespace logs** — use [debug](https://github.com/debug-js/debug) if all you need is conditional dev output with zero ceremony.
+> **Status:** Early release (0.x). The core API is stable, but details may evolve before 1.0.
+
+## When not to use Loggily
+
+- **You need the absolute fastest structured logger with a transport ecosystem.** Use [Pino](https://getpino.io/) for worker-thread transports, custom serializers, and log rotation.
+- **You need distributed tracing with vendor exporters and auto-instrumentation.** Use [OpenTelemetry](https://opentelemetry.io/).
 
 ## Documentation
 
@@ -122,32 +128,6 @@ For trivial arguments the difference is negligible. But for real-world logging
 - [Comparison](https://beorn.codes/loggily/guide/comparison) — vs Pino, Winston, Bunyan, debug
 - [Migration from debug](https://beorn.codes/loggily/guide/migration-from-debug) — step-by-step migration guide
 
-## Environment Variables
-
-| Variable       | Values                                  | Effect                                  |
-| -------------- | --------------------------------------- | --------------------------------------- |
-| `LOG_LEVEL`    | trace, debug, info, warn, error, silent | Minimum output level                    |
-| `LOG_FORMAT`   | console, json                           | Output format                           |
-| `DEBUG`        | `*`, namespace prefixes, `-prefix`      | Namespace filter (like `debug` package) |
-| `TRACE`        | `1`, `true`, or namespace prefixes      | Enable span output                      |
-| `TRACE_FORMAT` | json                                    | Force JSON for spans                    |
-| `NODE_ENV`     | production                              | Auto-enable JSON format                 |
-
-## API
-
-| Function                                                               | Description                                                   |
-| ---------------------------------------------------------------------- | ------------------------------------------------------------- |
-| `createLogger(name, props?)`                                           | Create a logger (disabled levels return `undefined` for `?.`) |
-| `.trace?.()` / `.debug?.()` / `.info?.()` / `.warn?.()` / `.error?.()` | Log at level (message + optional data)                        |
-| `.logger(namespace)`                                                   | Create child logger with extended namespace                   |
-| `.span(namespace, props?)`                                             | Create timed span (implements `Disposable`)                   |
-| `.child(context)`                                                      | Create child with structured context fields                   |
-| `addWriter(fn)` / `createFileWriter(path)`                             | Custom output writers                                         |
-| `setLogLevel()` / `setLogFormat()` / `enableSpans()`                   | Runtime configuration                                         |
-| `createWorkerLogger()` / `createWorkerLogHandler()`                    | Worker thread support (`loggily/worker`)                      |
-
-See the [full API reference](https://beorn.codes/loggily/api/) for all functions and options.
-
 ## License
 
 [MIT](LICENSE)

package/dist/index.d.mts

@@ -1,4 +1,333 @@
-import { n as FileWriterOptions, r as createFileWriter, t as FileWriter } from "./file-writer-BuQGFGRs.mjs";
-import { A as setDebugFilter, C as getCollectedSpans, D as getOutputMode, E as getLogLevel, F as setTraceFilter, I as spansAreEnabled, L as startCollecting, M as setLogLevel, N as setOutputMode, O as getTraceFilter, P as setSuppressConsole, R as stopCollecting, S as enableSpans, T as getLogFormat, _ as addWriter, a as LogLevel, b as createSpanDataProxy, c as OutputMode, d as SpanRecord, f as SpanRecorder, g as _setContextHooks, h as _setAmbientRecorder, i as LogFormat, j as setLogFormat, k as resetIds, l as SpanData, m as _clearContextHooks, n as LazyMessage, o as Logger, p as _ambientRecorder, r as LazyProps, s as OutputLogLevel, t as ConditionalLogger, u as SpanLogger, v as clearCollectedSpans, w as getDebugFilter, x as disableSpans, y as createLogger, z as writeSpan } from "./core-7D7sstHl.mjs";
-import { a as getIdFormat, c as setIdFormat, d as traceparent, l as setSampleRate, n as TraceparentOptions, o as getSampleRate, t as IdFormat } from "./tracing-2kv3HZ07.mjs";
-export { ConditionalLogger, type FileWriter, type FileWriterOptions, type IdFormat, LazyMessage, LazyProps, LogFormat, LogLevel, Logger, OutputLogLevel, OutputMode, SpanData, SpanLogger, SpanRecord, SpanRecorder, type TraceparentOptions, _ambientRecorder, _clearContextHooks, _setAmbientRecorder, _setContextHooks, addWriter, clearCollectedSpans, createFileWriter, createLogger, createSpanDataProxy, disableSpans, enableSpans, getCollectedSpans, getDebugFilter, getIdFormat, getLogFormat, getLogLevel, getOutputMode, getSampleRate, getTraceFilter, resetIds, setDebugFilter, setIdFormat, setLogFormat, setLogLevel, setOutputMode, setSampleRate, setSuppressConsole, setTraceFilter, spansAreEnabled, startCollecting, stopCollecting, traceparent, writeSpan };
+//#region src/core.d.ts
+/**
+ * loggily - Structured logging with spans
+ *
+ * Logger-first architecture: Span = Logger + Duration
+ *
+ * @example
+ * const log = createLogger('myapp')
+ *
+ * // Simple logging
+ * log.info('starting')
+ *
+ * // Lazy messages (function not called when level is disabled)
+ * log.debug?.(() => `expensive: ${computeState()}`)
+ *
+ * // Child loggers with context fields
+ * const reqLog = log.child({ requestId: 'abc' })
+ * reqLog.info('handling request')  // includes requestId in every message
+ *
+ * // With timing (span)
+ * {
+ *   using task = log.span('import', { file: 'data.csv' })
+ *   task.info('importing')
+ *   task.spanData.count = 42  // Set span attributes
+ *   // Auto-disposal on block exit → SPAN myapp:import (15ms)
+ * }
+ */
+/** Data passed to span recorders on disposal */
+interface SpanRecord {
+  readonly name: string;
+  readonly durationMs: number;
+}
+/** Interface for span duration recording — implemented by createMetricsCollector() in metrics.ts */
+interface SpanRecorder {
+  recordSpan(data: SpanRecord): void;
+}
+/**
+ * Ambient span recorder — auto-records when TRACE is active.
+ * Set by metrics.ts on import; can be replaced for testing.
+ * @internal
+ */
+declare let _ambientRecorder: SpanRecorder | null;
+declare function _setAmbientRecorder(recorder: SpanRecorder | null): void;
+/** Log levels that produce output */
+type OutputLogLevel = "trace" | "debug" | "info" | "warn" | "error";
+/** All log levels including silent (for filtering) */
+type LogLevel = OutputLogLevel | "silent";
+/** Message can be a string or a lazy function that returns a string */
+type LazyMessage = string | (() => string);
+/** Span props can be an object or a lazy function (skipped entirely via ?. when tracing is off) */
+type LazyProps = Record<string, unknown> | (() => Record<string, unknown>);
+/** Span data accessible via logger.spanData */
+interface SpanData {
+  readonly id: string;
+  readonly traceId: string;
+  readonly parentId: string | null;
+  readonly startTime: number;
+  readonly endTime: number | null;
+  readonly duration: number | null;
+  /** Custom attributes - set via direct property assignment */
+  [key: string]: unknown;
+}
+/** Logger interface */
+interface Logger {
+  /** Logger namespace (e.g., 'myapp:import') */
+  readonly name: string;
+  /** Props inherited from parent + own props */
+  readonly props: Readonly<Record<string, unknown>>;
+  /** Span data (non-null for span loggers, null for regular loggers) */
+  readonly spanData: SpanData | null;
+  trace(message: LazyMessage, data?: Record<string, unknown>): void;
+  debug(message: LazyMessage, data?: Record<string, unknown>): void;
+  info(message: LazyMessage, data?: Record<string, unknown>): void;
+  warn(message: LazyMessage, data?: Record<string, unknown>): void;
+  error(message: LazyMessage, data?: Record<string, unknown>): void;
+  /** Error overload - extracts message, stack, code from Error */
+  error(error: Error, data?: Record<string, unknown>): void;
+  /** Create child logger (extends namespace, inherits props) */
+  logger(namespace?: string, props?: Record<string, unknown>): Logger;
+  /** Create child span (extends namespace, inherits props, adds timing). Props can be lazy. */
+  span(namespace?: string, props?: LazyProps): SpanLogger;
+  /** Create child logger with context fields merged into every message */
+  child(context: Record<string, unknown>): Logger;
+  /** @deprecated Use .logger() instead for namespace-based children */
+  child(context: string): Logger;
+  /** End span manually (alternative to using keyword) */
+  end(): void;
+}
+/** Span logger - Logger with active span (spanData is non-null, implements Disposable) */
+interface SpanLogger extends Logger, Disposable {
+  readonly spanData: SpanData & {
+    /** Mutable attributes - set directly */[key: string]: unknown;
+  };
+}
+type LogWriter = (formatted: string, level: string) => void;
+/** Add a writer that receives all formatted log output. Returns unsubscribe. */
+declare function addWriter(writer: LogWriter): () => void;
+/** Suppress console output from the logger (writers still receive output). */
+declare function setSuppressConsole(value: boolean): void;
+/** Output mode for writeLog */
+type OutputMode = "console" | "stderr" | "writers-only";
+/** Set output mode for log messages (not spans — spans always use stderr). */
+declare function setOutputMode(mode: OutputMode): void;
+/** Get current output mode */
+declare function getOutputMode(): OutputMode;
+/** Set minimum log level */
+declare function setLogLevel(level: LogLevel): void;
+/** Get current log level */
+declare function getLogLevel(): LogLevel;
+/** Enable span output */
+declare function enableSpans(): void;
+/** Disable span output */
+declare function disableSpans(): void;
+/** Check if spans are enabled */
+declare function spansAreEnabled(): boolean;
+/**
+ * Set trace filter for namespace-based span output control.
+ * Only spans matching these namespace prefixes will be output.
+ * @param namespaces - Array of namespace prefixes, or null to disable filtering
+ */
+declare function setTraceFilter(namespaces: string[] | null): void;
+/** Get current trace filter (null means no filtering) */
+declare function getTraceFilter(): string[] | null;
+/**
+ * Set debug namespace filter (like the `debug` npm package).
+ * When set, only loggers matching these namespace prefixes produce output.
+ * Supports negative patterns with `-` prefix (e.g., ["-km:noisy"]).
+ * Also ensures log level is at least `debug`.
+ * @param namespaces - Array of namespace prefixes (prefix with `-` to exclude), or null to disable
+ */
+declare function setDebugFilter(namespaces: string[] | null): void;
+/** Get current debug namespace filter (null means no filtering) */
+declare function getDebugFilter(): string[] | null;
+/** Output format: human-readable console or structured JSON */
+type LogFormat = "console" | "json";
+/** Set log output format */
+declare function setLogFormat(format: LogFormat): void;
+/** Get current log output format */
+declare function getLogFormat(): LogFormat;
+declare function resetIds(): void;
+/**
+ * Register context propagation hooks (called by context.ts).
+ * @internal
+ */
+declare function _setContextHooks(hooks: {
+  getContextTags: () => Record<string, string>;
+  getContextParent: () => {
+    spanId: string;
+    traceId: string;
+  } | null;
+  enterContext: (spanId: string, traceId: string, parentId: string | null) => void;
+  exitContext: (spanId: string) => void;
+}): void;
+/**
+ * Clear context propagation hooks (called by disableContextPropagation).
+ * @internal
+ */
+declare function _clearContextHooks(): void;
+declare function writeSpan(namespace: string, duration: number, attrs: Record<string, unknown>): void;
+interface SpanDataFields {
+  id: string;
+  traceId: string;
+  parentId: string | null;
+  startTime: number;
+  endTime: number | null;
+  duration: number | null;
+}
+/**
+ * Create a proxy that exposes span metadata as readonly and custom attributes as writable.
+ * Shared between core logger spans and worker logger spans.
+ */
+declare function createSpanDataProxy(getFields: () => SpanDataFields, attrs: Record<string, unknown>): SpanData;
+/** Enable span collection for analysis */
+declare function startCollecting(): void;
+/** Stop collecting and return collected spans */
+declare function stopCollecting(): SpanData[];
+/** Get collected spans */
+declare function getCollectedSpans(): SpanData[];
+/** Clear collected spans */
+declare function clearCollectedSpans(): void;
+/**
+ * Logger with optional methods — returns undefined for disabled levels.
+ * Use with optional chaining: `log.debug?.("msg")` for zero-overhead when disabled.
+ *
+ * Defined as an explicit interface (not Omit<Logger,...>) so that
+ * oxlint's type-aware mode can resolve it without advanced type inference.
+ */
+interface ConditionalLogger {
+  readonly name: string;
+  readonly props: Readonly<Record<string, unknown>>;
+  readonly spanData: SpanData | null;
+  trace?: (message: LazyMessage, data?: Record<string, unknown>) => void;
+  debug?: (message: LazyMessage, data?: Record<string, unknown>) => void;
+  info?: (message: LazyMessage, data?: Record<string, unknown>) => void;
+  warn?: (message: LazyMessage, data?: Record<string, unknown>) => void;
+  error?: {
+    (message: LazyMessage, data?: Record<string, unknown>): void;
+    (error: Error, data?: Record<string, unknown>): void;
+  };
+  logger(namespace?: string, props?: Record<string, unknown>): Logger;
+  span(namespace?: string, props?: LazyProps): SpanLogger;
+  child(context: Record<string, unknown>): Logger;
+  child(context: string): Logger;
+  end(): void;
+}
+/**
+ * Create a logger for a component.
+ * Returns undefined for disabled levels - use with optional chaining for zero overhead.
+ *
+ * Log levels (most → least verbose): trace < debug < info < warn < error < silent
+ * Default level: info (trace and debug disabled)
+ *
+ * @example
+ * const log = createLogger('myapp')
+ *
+ * // All methods support ?. for zero-overhead when disabled
+ * log.trace?.(`very verbose: ${expensiveDebug()}`)  // Skipped at info level
+ * log.debug?.(`debug: ${getState()}`)               // Skipped at info level
+ * log.info?.('starting')                            // Enabled at info level
+ * log.warn?.('deprecated')                          // Enabled at info level
+ * log.error?.('failed')                             // Enabled at info level
+ *
+ * // With -q flag or LOG_LEVEL=warn:
+ * log.info?.('starting')  // Now skipped - info < warn
+ *
+ * // With initial props
+ * const log = createLogger('myapp', { version: '1.0' })
+ *
+ * // Create spans
+ * {
+ *   using task = log.span('import', { file: 'data.csv' })
+ *   task.info?.('importing')
+ *   task.spanData.count = 42
+ * }
+ */
+declare function createLogger(name: string, props?: Record<string, unknown>): ConditionalLogger;
+//#endregion
+//#region src/file-writer.d.ts
+/**
+ * File writer for loggily — Node.js/Bun only.
+ *
+ * Separated from core logger to allow tree-shaking in browser bundles.
+ * Uses dynamic import("node:fs") to avoid static dependency on Node APIs.
+ */
+/** Options for creating an async buffered file writer */
+interface FileWriterOptions {
+  /** Buffer size threshold in bytes before flushing (default: 4096) */
+  bufferSize?: number;
+  /** Flush interval in milliseconds (default: 100) */
+  flushInterval?: number;
+}
+/** An async buffered file writer with automatic flushing */
+interface FileWriter {
+  /** Write a line to the buffer (appends newline) */
+  write(line: string): void;
+  /** Flush the buffer immediately */
+  flush(): void;
+  /** Close the writer and flush remaining buffer */
+  close(): void;
+}
+/**
+ * Create an async buffered file writer for log output.
+ * Buffers writes and flushes on size threshold or interval.
+ * Registers a process.on('exit') handler to flush remaining buffer.
+ *
+ * **Node.js/Bun only** — not available in browser environments.
+ *
+ * @param filePath - Path to the log file (opened in append mode)
+ * @param options - Buffer size and flush interval configuration
+ * @returns FileWriter with write, flush, and close methods
+ *
+ * @example
+ * const writer = createFileWriter('/tmp/app.log')
+ * const unsubscribe = addWriter((formatted) => writer.write(formatted))
+ *
+ * // On shutdown:
+ * unsubscribe()
+ * writer.close()
+ */
+declare function createFileWriter(filePath: string, options?: FileWriterOptions): FileWriter;
+//#endregion
+//#region src/tracing.d.ts
+/** Supported ID formats */
+type IdFormat = "simple" | "w3c";
+/**
+ * Set the ID format for new spans and traces.
+ * - "simple": sp_1, sp_2, tr_1, tr_2 (default, lightweight)
+ * - "w3c": 32-char hex trace ID, 16-char hex span ID (W3C Trace Context compatible)
+ */
+declare function setIdFormat(format: IdFormat): void;
+/** Get the current ID format */
+declare function getIdFormat(): IdFormat;
+/** Options for traceparent header formatting */
+interface TraceparentOptions {
+  /** Whether this span is sampled. Defaults to true for backwards compatibility. */
+  sampled?: boolean;
+}
+/**
+ * Format a W3C traceparent header from span data.
+ *
+ * Format: `{version}-{trace-id}-{span-id}-{trace-flags}`
+ * - version: "00" (current W3C spec version)
+ * - trace-id: 32 hex chars (128 bits)
+ * - span-id: 16 hex chars (64 bits)
+ * - trace-flags: "01" (sampled) or "00" (not sampled)
+ *
+ * Works with both simple and W3C ID formats. Simple IDs are zero-padded to spec length.
+ *
+ * @param spanData - Span data with id and traceId
+ * @param options - Optional settings (sampled flag). Defaults to sampled=true.
+ * @returns W3C traceparent header string
+ *
+ * @example
+ * ```typescript
+ * const span = log.span("http-request")
+ * const header = traceparent(span.spanData)
+ * // → "00-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6-1a2b3c4d5e6f7a8b-01"
+ * fetch(url, { headers: { traceparent: header } })
+ * ```
+ */
+declare function traceparent(spanData: SpanData, options?: TraceparentOptions): string;
+/**
+ * Set the head-based sampling rate for new traces.
+ * Applied at trace creation — all spans within a sampled trace are kept.
+ *
+ * @param rate - Sampling rate from 0.0 (sample nothing) to 1.0 (sample everything, default)
+ */
+declare function setSampleRate(rate: number): void;
+/** Get the current sampling rate */
+declare function getSampleRate(): number;
+//#endregion
+export { ConditionalLogger, type FileWriter, type FileWriterOptions, type IdFormat, LazyMessage, LazyProps, LogFormat, LogLevel, Logger, OutputLogLevel, OutputMode, SpanData, SpanLogger, SpanRecord, SpanRecorder, type TraceparentOptions, _ambientRecorder, _clearContextHooks, _setAmbientRecorder, _setContextHooks, addWriter, clearCollectedSpans, createFileWriter, createLogger, createSpanDataProxy, disableSpans, enableSpans, getCollectedSpans, getDebugFilter, getIdFormat, getLogFormat, getLogLevel, getOutputMode, getSampleRate, getTraceFilter, resetIds, setDebugFilter, setIdFormat, setLogFormat, setLogLevel, setOutputMode, setSampleRate, setSuppressConsole, setTraceFilter, spansAreEnabled, startCollecting, stopCollecting, traceparent, writeSpan };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/core.ts","../src/file-writer.ts","../src/tracing.ts"],"mappings":"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"}