loggily 0.7.0 → 0.10.0

package/README.md

@@ -1,175 +1,88 @@
-# Loggily
-
-**Clarity without the clutter.**
-
-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)
 [![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)
 
-Most apps end up with three logging tools: `debug` for local troubleshooting, a JSON logger for production, and ad-hoc timers or a tracing SDK for performance. Three APIs, three configs, three output formats.
+# Loggily — Clarity without the clutter
 
-Loggily replaces all three with one namespace tree and one output pipeline. Pure TypeScript, zero dependencies, ~3 KB.
+**Debugs, logs, and spans — structured and dev, server and browser — one API.**
+
+Replace `debug` + your JSON logger + ad-hoc timers with one namespace tree and one output pipeline. Pure TypeScript, zero dependencies, ~3 KB.
 
 ```typescript
 import { createLogger } from "loggily"
 
-const log = createLogger("myapp", [{ level: "debug" }, console])
+const log = createLogger("myapp") // zero config — reads LOG_LEVEL, DEBUG from env
 
 log.info?.("server started", { port: 3000 })
 log.debug?.("cache hit", { key: "user:42" })
 log.error?.(new Error("connection lost"))
 ```
 
-Readable, colorized output in development:
-
-```
-14:32:15 INFO myapp server started {port: 3000}
-14:32:15 DEBUG myapp cache hit {key: "user:42"}
-14:32:15 ERROR myapp connection lost
-```
-
-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 }
-```
-
-## Why the `?.`
-
-Disabled logs should not build strings, serialize objects, or compute snapshots just to throw them away.
-
-With most loggers, this work still happens:
-
-```typescript
-log.debug(`state: ${JSON.stringify(computeExpensiveState())}`)
-// computeExpensiveState() runs even when debug is off
-```
-
-With Loggily, optional chaining short-circuits the entire call:
-
-```typescript
-log.debug?.(`state: ${JSON.stringify(computeExpensiveState())}`)
-// nothing runs when debug is off — not the function, not the stringify, not the template
-```
+**The `?.` optional chaining trick** short-circuits the entire call when a log level is disabled, so nothing evaluates — not the string interpolation, not the function calls, nothing. In benchmarks, that's [~22x faster](https://loggily.dev/guide/benchmarks) than conventional noop loggers. [See how Loggily compares →](https://loggily.dev/guide/comparison)
 
-In benchmarks with expensive disabled log arguments, this is [~22x faster](https://beorn.codes/loggily/guide/benchmarks) than a conventional noop logger.
+## Getting Started
 
-## Install
+```console
+$ npm install loggily
 
-```bash
-npm install loggily
+$ DEBUG='*' node app                        # show all debug output
+$ DEBUG='myapp:db' node app                 # only database logs
+$ LOG_FILE=/tmp/app.log node app            # write to file
+$ NODE_ENV=production node app              # structured JSON output
+$ TRACE=1 node app                          # enable span timing
 ```
 
-| 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
-
-- **Config pipeline** -- second arg to `createLogger` is a config array: objects configure (`{ level, ns, format }`), arrays branch, values write. Pass `console` for terminal output, `{ file: "/path" }` for file output, or functions for custom stages.
-- **Namespace hierarchy** -- organize logs with `:` separators. `DEBUG=myapp:db` shows only database output, compatible with the same patterns as 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.
-- **Error overloads** -- `log.error?.(err)`, `log.error?.(err, "msg")`, and `log.error?.(err, "msg", data)`.
-- **Worker threads** -- forward logs from workers to the main thread with full type safety.
-
-### Config Array
-
 ```typescript
 import { createLogger } from "loggily"
+import { toOtel } from "loggily/otel"
 
-// Objects configure, arrays branch, values write
+// Config pipeline — objects configure, arrays branch, values write
 const log = createLogger("myapp", [
-  { level: "debug", ns: "-sql" },
-  console,
-  { file: "/tmp/app.log", level: "error", format: "json" },
+  { level: "debug", metrics: true }, // config object — sets scope
+  toOtel({ api: otelApi }), // stage — forwards to Jaeger/Grafana/Datadog
+  pinoTransport, // writable — { write } receives events
+  { file: "...", format: "json" }, // file sink — formatted strings
+  [{ level: "warn" }, { file: "..." }], // branch — sub-pipeline with own scope
+  console, // colorized dev output, JSON in production
 ])
-```
 
-When no config array is provided, loggily reads `LOG_LEVEL`, `DEBUG`, `LOG_FORMAT`, and `NODE_ENV` from the environment.
+// Structured logging
+log.info?.("server started", { port: 3000 })
+log.debug?.(`state: ${expensiveFunc()}`) // skipped if debug off
+log.error?.(new Error("connection lost"))
 
-### Spans
+// Child loggers — extend namespace, add context
+const dbLog = log.child("db", { pool: "main" }) // namespace: "myapp:db"
 
-```typescript
+// Spans — time any operation, auto-track parent/child + trace IDs
+// AsyncLocalStorage propagation: logs in async chains inherit span context
 {
-  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()
+  using span = dbLog.span?.("query", { table: "users" })
+  const users = await queryUsers() // logs inside queryUsers() get trace IDs
+  if (span) span.spanData.count = users.length
 }
-```
-
-### Common configuration
-
-| Variable     | Example                   | Effect                                                 |
-| ------------ | ------------------------- | ------------------------------------------------------ |
-| `DEBUG`      | `myapp:db,-myapp:sql`     | Namespace filter (compatible with 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                                     |
-
-See the [full environment variable reference](https://beorn.codes/loggily/api/configuration).
-
-### Types
+// → SPAN myapp:db:query (45ms) {count: 100, table: "users"}
 
-Key types exported for power users:
+// Metrics — p50/p95/p99 from spans
+log.metrics.summary() // myapp:db:query: 42 spans, mean=3.2ms, p95=8.4ms
 
-| Type                | Description                                                      |
-| ------------------- | ---------------------------------------------------------------- |
-| `LogEvent`          | A log message event (kind, level, namespace, message, props)     |
-| `SpanEvent`         | A span timing event (kind, namespace, duration, spanId, traceId) |
-| `Event`             | `LogEvent \| SpanEvent`                                          |
-| `Stage`             | `(event: Event) => Event \| null \| void`                        |
-| `Pipeline`          | `{ dispatch, level, dispose }`                                   |
-| `ConditionalLogger` | Logger with `?.`-compatible methods                              |
-
-`buildPipeline()` and `defaultPipeline()` are exported for direct pipeline construction.
-
-## Compatibility
-
-- **`DEBUG=` compatible** -- uses the same namespace filter patterns as the `debug` package
-- **Works with Pino transports** -- custom stage functions can forward events to any sink
-- **W3C Trace Context** -- `traceparent()` generates standard trace headers
-- **OpenTelemetry compatible** -- span events include `spanId`, `traceId`, `parentId`
-
-## Why this exists
+// Composable — build custom factories
+const myCreateLogger = pipe(baseCreateLogger, withSpans(), myPlugin())
+```
 
-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.
+Also supports [async context propagation](https://loggily.dev/api/context), [worker threads](https://loggily.dev/guide/workers), and [browser](https://loggily.dev/guide/getting-started#browser-support).
 
-> **Status:** Early release (0.x). The core API is stable, but details may evolve before 1.0.
+**Works with:** [OpenTelemetry](https://loggily.dev/api/otel) (Jaeger, Grafana, Datadog, any OTLP backend) · [Pino transports](https://loggily.dev/guide/destinations#pino) · Sentry · Elasticsearch · AWS CloudWatch · Prometheus · [W3C Trace Context](https://loggily.dev/api/tracing) · [`DEBUG=` patterns](https://loggily.dev/guide/journey#namespaces) · [See all destinations →](https://loggily.dev/guide/destinations)
 
-## When not to use Loggily
+## About
 
-- **You need worker-thread transport pipelines with log rotation and dozens of plugins.** [Pino](https://getpino.io/) has a mature transport ecosystem for this.
-- **You need distributed tracing with vendor exporters and auto-instrumentation.** [OpenTelemetry](https://opentelemetry.io/) is the industry standard.
+Born from the frustration of juggling separate systems for debug logging, structured production logs, metrics, and spans — each with its own API, config, and propagation — and then duplicating the whole setup again because browser and terminal needed completely different pipelines and destinations. Loggily unifies it all: one API, one config, one pipeline that works everywhere, without the overhead when logs are off.
 
-## Documentation
+**Requirements:** Node.js ≥ 23.6 or Bun ≥ 1.0. ESM-only. TypeScript 5.2+ for `using` (`.end()` works on any version). [Browser supported](https://loggily.dev/guide/getting-started#browser-support) via conditional export.
 
-- **[Get Started](https://beorn.codes/loggily/guide/journey)** -- progressive guide from first log to full observability
-- **[Full docs site](https://beorn.codes/loggily/)** -- guides, API reference, migration guides
-- [Comparison](https://beorn.codes/loggily/guide/comparison) -- what Loggily does, compatibility, when to use something else
-- [Migration from debug](https://beorn.codes/loggily/guide/migration-from-debug) -- step-by-step migration guide
+**When not to use Loggily:** if you need auto-instrumentation (HTTP, database, gRPC) use OpenTelemetry's SDK directly; if you need log rotation or dozens of transport plugins, Pino's ecosystem is deeper.
 
-## License
+**Docs:** [Get Started](https://loggily.dev/guide/getting-started) · [Full docs](https://loggily.dev/) · [Comparison](https://loggily.dev/guide/comparison) · [Why Loggily](https://loggily.dev/guide/why)
 
 [MIT](LICENSE)

package/dist/context.d.mts

@@ -14,10 +14,10 @@
  *
  * const log = createLogger("myapp")
  * {
- *   using span = log.span("request")
+ *   using span = log.span?.("request")
  *   // All logs and child spans within this async context
  *   // automatically inherit trace_id and span_id
- *   log.info("inside span") // auto-tagged with trace_id, span_id
+ *   log.info?.("inside span") // auto-tagged with trace_id, span_id
  *
  *   const current = getCurrentSpan()
  *   // current === { spanId: "sp_1", traceId: "tr_1", parentId: null }

package/dist/context.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.mts","names":[],"sources":["../src/context.ts"],"mappings":";;AAgCA;;;;;;;;;AA2BA;;;;;AAuBA;;;;;AAMA;;;;;AASA;AAAA,UAjEiB,WAAA;EAAA,SACN,MAAA;EAAA,SACA,OAAA;EAAA,SACA,QAAA;AAAA;;;;;;;;iBAwBK,wBAAA,CAAA;AAuEhB;;;;AAAA,iBAhDgB,yBAAA,CAAA;AAsEhB;AAAA,iBAhEgB,2BAAA,CAAA;;;;;;iBASA,cAAA,CAAA,GAAkB,WAAA;;;;;;;;;AAiElC;;;iBAjDgB,gBAAA,CAAiB,MAAA,UAAgB,OAAA,UAAiB,QAAA;;;;;;;;iBAiBlD,eAAA,CAAgB,MAAA;;;;;;;;;iBAsBhB,gBAAA,GAAA,CAAoB,OAAA,EAAS,WAAA,EAAa,EAAA,QAAU,CAAA,GAAI,CAAA;;;;;;iBAUxD,cAAA,CAAA,GAAkB,MAAA"}
+{"version":3,"file":"context.d.mts","names":[],"sources":["../src/context.ts"],"mappings":";;AAgCA;;;;;;;;;AA2BA;;;;;AAuBA;;;;;AAMA;;;;;AASA;AAAA,UAjEiB,WAAA;EAAA,SACN,MAAA;EAAA,SACA,OAAA;EAAA,SACA,QAAA;AAAA;;;;;;;;iBAwBK,wBAAA,CAAA;AA2EhB;;;;AAAA,iBApDgB,yBAAA,CAAA;AA0EhB;AAAA,iBApEgB,2BAAA,CAAA;;;;;;iBASA,cAAA,CAAA,GAAkB,WAAA;;;;;;;;;AAqElC;;;iBArDgB,gBAAA,CACd,MAAA,UACA,OAAA,UACA,QAAA;;;;;;;;iBAkBc,eAAA,CAAgB,MAAA;;;;;;;;;iBAsBhB,gBAAA,GAAA,CAAoB,OAAA,EAAS,WAAA,EAAa,EAAA,QAAU,CAAA,GAAI,CAAA;;;;;;iBAUxD,cAAA,CAAA,GAAkB,MAAA"}

package/dist/context.mjs

@@ -1,4 +1,4 @@
-import { i as _setContextHooks, n as _clearContextHooks } from "./core-Du3sIje6.mjs";
+import { n as _setContextHooks, t as _clearContextHooks } from "./core-Byd3DY71.mjs";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/context.ts
 /**
@@ -16,10 +16,10 @@ import { AsyncLocalStorage } from "node:async_hooks";
 *
 * const log = createLogger("myapp")
 * {
-*   using span = log.span("request")
+*   using span = log.span?.("request")
 *   // All logs and child spans within this async context
 *   // automatically inherit trace_id and span_id
-*   log.info("inside span") // auto-tagged with trace_id, span_id
+*   log.info?.("inside span") // auto-tagged with trace_id, span_id
 *
 *   const current = getCurrentSpan()
 *   // current === { spanId: "sp_1", traceId: "tr_1", parentId: null }

package/dist/context.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"context.mjs","names":[],"sources":["../src/context.ts"],"sourcesContent":["/**\n * AsyncLocalStorage-based context propagation for loggily — Node.js/Bun only.\n *\n * Separated from core logger to allow tree-shaking in browser bundles.\n * When enabled, new spans automatically parent to the current context span,\n * and writeLog() auto-tags with trace_id/span_id from context.\n *\n * @example\n * ```typescript\n * import { enableContextPropagation, getCurrentSpan } from \"loggily/context\"\n *\n * enableContextPropagation()\n *\n * const log = createLogger(\"myapp\")\n * {\n *   using span = log.span(\"request\")\n *   // All logs and child spans within this async context\n *   // automatically inherit trace_id and span_id\n *   log.info(\"inside span\") // auto-tagged with trace_id, span_id\n *\n *   const current = getCurrentSpan()\n *   // current === { spanId: \"sp_1\", traceId: \"tr_1\", parentId: null }\n * }\n * ```\n */\n\nimport { AsyncLocalStorage } from \"node:async_hooks\"\nimport { _setContextHooks, _clearContextHooks } from \"./core.js\"\n\n// ============ Types ============\n\n/** Minimal span context stored in AsyncLocalStorage */\nexport interface SpanContext {\n  readonly spanId: string\n  readonly traceId: string\n  readonly parentId: string | null\n}\n\n// ============ State ============\n\nlet storage: AsyncLocalStorage<SpanContext> | null = null\nlet contextEnabled = false\n\n/**\n * Map from spanId → the SpanContext that was active when the span was entered.\n * Used to restore the exact previous context on exit, avoiding corruption\n * from non-LIFO end() ordering.\n */\nconst previousContexts = new Map<string, SpanContext | null>()\n\n// ============ API ============\n\n/**\n * Enable AsyncLocalStorage-based context propagation.\n * Once enabled, new spans automatically parent to the current context span,\n * and log messages are auto-tagged with trace_id/span_id.\n *\n * **Node.js/Bun only** — not available in browser environments.\n */\nexport function enableContextPropagation(): void {\n  if (!storage) {\n    storage = new AsyncLocalStorage<SpanContext>()\n  }\n  contextEnabled = true\n\n  // Register hooks with core.ts\n  _setContextHooks({\n    getContextTags,\n    getContextParent() {\n      const span = getCurrentSpan()\n      if (!span) return null\n      return { spanId: span.spanId, traceId: span.traceId }\n    },\n    enterContext: enterSpanContext,\n    exitContext: exitSpanContext,\n  })\n}\n\n/**\n * Disable context propagation.\n * Existing spans continue to work, but new spans won't auto-parent.\n */\nexport function disableContextPropagation(): void {\n  contextEnabled = false\n  _clearContextHooks()\n}\n\n/** Check if context propagation is enabled */\nexport function isContextPropagationEnabled(): boolean {\n  return contextEnabled\n}\n\n/**\n * Get the current span context from AsyncLocalStorage.\n * Returns null if no span is active in the current async context,\n * or if context propagation is not enabled.\n */\nexport function getCurrentSpan(): SpanContext | null {\n  if (!contextEnabled || !storage) return null\n  return storage.getStore() ?? null\n}\n\n/**\n * Enter a span context for the remainder of the current synchronous execution\n * and any async operations started from it. Used by the logger when creating\n * spans with `using` — since `using` doesn't wrap user code in a callback,\n * `enterWith()` is the right primitive.\n *\n * Captures the full previous SpanContext snapshot so it can be restored\n * exactly on exit, even with non-LIFO end() ordering.\n *\n * @internal\n */\nexport function enterSpanContext(spanId: string, traceId: string, parentId: string | null): void {\n  if (!contextEnabled || !storage) return\n\n  // Capture the full previous context before overwriting\n  const previous = storage.getStore() ?? null\n  previousContexts.set(spanId, previous)\n\n  storage.enterWith({ spanId, traceId, parentId })\n}\n\n/**\n * Restore the previous span context (called when a span ends).\n * Restores the exact SpanContext snapshot captured at enter time,\n * preventing corruption from non-LIFO end() ordering.\n *\n * @internal\n */\nexport function exitSpanContext(spanId: string): void {\n  if (!contextEnabled || !storage) return\n\n  const previous = previousContexts.get(spanId)\n  previousContexts.delete(spanId)\n\n  if (previous) {\n    storage.enterWith(previous)\n  } else {\n    // No previous context — exit entirely\n    storage.enterWith(undefined as unknown as SpanContext)\n  }\n}\n\n/**\n * Run a function within a span context.\n * Used for explicit context scoping (e.g., in request handlers).\n *\n * @param context - The span context to set\n * @param fn - The function to run within the context\n * @returns The return value of fn\n */\nexport function runInSpanContext<T>(context: SpanContext, fn: () => T): T {\n  if (!contextEnabled || !storage) return fn()\n  return storage.run(context, fn)\n}\n\n/**\n * Get the context tags (trace_id, span_id) for the current async context.\n * Used by writeLog() to auto-tag log messages.\n * Returns empty object if context propagation is disabled or no span is active.\n */\nexport function getContextTags(): Record<string, string> {\n  const span = getCurrentSpan()\n  if (!span) return {}\n  return {\n    trace_id: span.traceId,\n    span_id: span.spanId,\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,IAAI,UAAiD;AACrD,IAAI,iBAAiB;;;;;;AAOrB,MAAM,mCAAmB,IAAI,KAAiC;;;;;;;;AAW9D,SAAgB,2BAAiC;AAC/C,KAAI,CAAC,QACH,WAAU,IAAI,mBAAgC;AAEhD,kBAAiB;AAGjB,kBAAiB;EACf;EACA,mBAAmB;GACjB,MAAM,OAAO,gBAAgB;AAC7B,OAAI,CAAC,KAAM,QAAO;AAClB,UAAO;IAAE,QAAQ,KAAK;IAAQ,SAAS,KAAK;IAAS;;EAEvD,cAAc;EACd,aAAa;EACd,CAAC;;;;;;AAOJ,SAAgB,4BAAkC;AAChD,kBAAiB;AACjB,qBAAoB;;;AAItB,SAAgB,8BAAuC;AACrD,QAAO;;;;;;;AAQT,SAAgB,iBAAqC;AACnD,KAAI,CAAC,kBAAkB,CAAC,QAAS,QAAO;AACxC,QAAO,QAAQ,UAAU,IAAI;;;;;;;;;;;;;AAc/B,SAAgB,iBAAiB,QAAgB,SAAiB,UAA+B;AAC/F,KAAI,CAAC,kBAAkB,CAAC,QAAS;CAGjC,MAAM,WAAW,QAAQ,UAAU,IAAI;AACvC,kBAAiB,IAAI,QAAQ,SAAS;AAEtC,SAAQ,UAAU;EAAE;EAAQ;EAAS;EAAU,CAAC;;;;;;;;;AAUlD,SAAgB,gBAAgB,QAAsB;AACpD,KAAI,CAAC,kBAAkB,CAAC,QAAS;CAEjC,MAAM,WAAW,iBAAiB,IAAI,OAAO;AAC7C,kBAAiB,OAAO,OAAO;AAE/B,KAAI,SACF,SAAQ,UAAU,SAAS;KAG3B,SAAQ,UAAU,KAAA,EAAoC;;;;;;;;;;AAY1D,SAAgB,iBAAoB,SAAsB,IAAgB;AACxE,KAAI,CAAC,kBAAkB,CAAC,QAAS,QAAO,IAAI;AAC5C,QAAO,QAAQ,IAAI,SAAS,GAAG;;;;;;;AAQjC,SAAgB,iBAAyC;CACvD,MAAM,OAAO,gBAAgB;AAC7B,KAAI,CAAC,KAAM,QAAO,EAAE;AACpB,QAAO;EACL,UAAU,KAAK;EACf,SAAS,KAAK;EACf"}
+{"version":3,"file":"context.mjs","names":[],"sources":["../src/context.ts"],"sourcesContent":["/**\n * AsyncLocalStorage-based context propagation for loggily — Node.js/Bun only.\n *\n * Separated from core logger to allow tree-shaking in browser bundles.\n * When enabled, new spans automatically parent to the current context span,\n * and writeLog() auto-tags with trace_id/span_id from context.\n *\n * @example\n * ```typescript\n * import { enableContextPropagation, getCurrentSpan } from \"loggily/context\"\n *\n * enableContextPropagation()\n *\n * const log = createLogger(\"myapp\")\n * {\n *   using span = log.span?.(\"request\")\n *   // All logs and child spans within this async context\n *   // automatically inherit trace_id and span_id\n *   log.info?.(\"inside span\") // auto-tagged with trace_id, span_id\n *\n *   const current = getCurrentSpan()\n *   // current === { spanId: \"sp_1\", traceId: \"tr_1\", parentId: null }\n * }\n * ```\n */\n\nimport { AsyncLocalStorage } from \"node:async_hooks\"\nimport { _setContextHooks, _clearContextHooks } from \"./core.js\"\n\n// ============ Types ============\n\n/** Minimal span context stored in AsyncLocalStorage */\nexport interface SpanContext {\n  readonly spanId: string\n  readonly traceId: string\n  readonly parentId: string | null\n}\n\n// ============ State ============\n\nlet storage: AsyncLocalStorage<SpanContext> | null = null\nlet contextEnabled = false\n\n/**\n * Map from spanId → the SpanContext that was active when the span was entered.\n * Used to restore the exact previous context on exit, avoiding corruption\n * from non-LIFO end() ordering.\n */\nconst previousContexts = new Map<string, SpanContext | null>()\n\n// ============ API ============\n\n/**\n * Enable AsyncLocalStorage-based context propagation.\n * Once enabled, new spans automatically parent to the current context span,\n * and log messages are auto-tagged with trace_id/span_id.\n *\n * **Node.js/Bun only** — not available in browser environments.\n */\nexport function enableContextPropagation(): void {\n  if (!storage) {\n    storage = new AsyncLocalStorage<SpanContext>()\n  }\n  contextEnabled = true\n\n  // Register hooks with core.ts\n  _setContextHooks({\n    getContextTags,\n    getContextParent() {\n      const span = getCurrentSpan()\n      if (!span) return null\n      return { spanId: span.spanId, traceId: span.traceId }\n    },\n    enterContext: enterSpanContext,\n    exitContext: exitSpanContext,\n  })\n}\n\n/**\n * Disable context propagation.\n * Existing spans continue to work, but new spans won't auto-parent.\n */\nexport function disableContextPropagation(): void {\n  contextEnabled = false\n  _clearContextHooks()\n}\n\n/** Check if context propagation is enabled */\nexport function isContextPropagationEnabled(): boolean {\n  return contextEnabled\n}\n\n/**\n * Get the current span context from AsyncLocalStorage.\n * Returns null if no span is active in the current async context,\n * or if context propagation is not enabled.\n */\nexport function getCurrentSpan(): SpanContext | null {\n  if (!contextEnabled || !storage) return null\n  return storage.getStore() ?? null\n}\n\n/**\n * Enter a span context for the remainder of the current synchronous execution\n * and any async operations started from it. Used by the logger when creating\n * spans with `using` — since `using` doesn't wrap user code in a callback,\n * `enterWith()` is the right primitive.\n *\n * Captures the full previous SpanContext snapshot so it can be restored\n * exactly on exit, even with non-LIFO end() ordering.\n *\n * @internal\n */\nexport function enterSpanContext(\n  spanId: string,\n  traceId: string,\n  parentId: string | null,\n): void {\n  if (!contextEnabled || !storage) return\n\n  // Capture the full previous context before overwriting\n  const previous = storage.getStore() ?? null\n  previousContexts.set(spanId, previous)\n\n  storage.enterWith({ spanId, traceId, parentId })\n}\n\n/**\n * Restore the previous span context (called when a span ends).\n * Restores the exact SpanContext snapshot captured at enter time,\n * preventing corruption from non-LIFO end() ordering.\n *\n * @internal\n */\nexport function exitSpanContext(spanId: string): void {\n  if (!contextEnabled || !storage) return\n\n  const previous = previousContexts.get(spanId)\n  previousContexts.delete(spanId)\n\n  if (previous) {\n    storage.enterWith(previous)\n  } else {\n    // No previous context — exit entirely\n    storage.enterWith(undefined as unknown as SpanContext)\n  }\n}\n\n/**\n * Run a function within a span context.\n * Used for explicit context scoping (e.g., in request handlers).\n *\n * @param context - The span context to set\n * @param fn - The function to run within the context\n * @returns The return value of fn\n */\nexport function runInSpanContext<T>(context: SpanContext, fn: () => T): T {\n  if (!contextEnabled || !storage) return fn()\n  return storage.run(context, fn)\n}\n\n/**\n * Get the context tags (trace_id, span_id) for the current async context.\n * Used by writeLog() to auto-tag log messages.\n * Returns empty object if context propagation is disabled or no span is active.\n */\nexport function getContextTags(): Record<string, string> {\n  const span = getCurrentSpan()\n  if (!span) return {}\n  return {\n    trace_id: span.traceId,\n    span_id: span.spanId,\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,IAAI,UAAiD;AACrD,IAAI,iBAAiB;;;;;;AAOrB,MAAM,mCAAmB,IAAI,KAAiC;;;;;;;;AAW9D,SAAgB,2BAAiC;AAC/C,KAAI,CAAC,QACH,WAAU,IAAI,mBAAgC;AAEhD,kBAAiB;AAGjB,kBAAiB;EACf;EACA,mBAAmB;GACjB,MAAM,OAAO,gBAAgB;AAC7B,OAAI,CAAC,KAAM,QAAO;AAClB,UAAO;IAAE,QAAQ,KAAK;IAAQ,SAAS,KAAK;IAAS;;EAEvD,cAAc;EACd,aAAa;EACd,CAAC;;;;;;AAOJ,SAAgB,4BAAkC;AAChD,kBAAiB;AACjB,qBAAoB;;;AAItB,SAAgB,8BAAuC;AACrD,QAAO;;;;;;;AAQT,SAAgB,iBAAqC;AACnD,KAAI,CAAC,kBAAkB,CAAC,QAAS,QAAO;AACxC,QAAO,QAAQ,UAAU,IAAI;;;;;;;;;;;;;AAc/B,SAAgB,iBACd,QACA,SACA,UACM;AACN,KAAI,CAAC,kBAAkB,CAAC,QAAS;CAGjC,MAAM,WAAW,QAAQ,UAAU,IAAI;AACvC,kBAAiB,IAAI,QAAQ,SAAS;AAEtC,SAAQ,UAAU;EAAE;EAAQ;EAAS;EAAU,CAAC;;;;;;;;;AAUlD,SAAgB,gBAAgB,QAAsB;AACpD,KAAI,CAAC,kBAAkB,CAAC,QAAS;CAEjC,MAAM,WAAW,iBAAiB,IAAI,OAAO;AAC7C,kBAAiB,OAAO,OAAO;AAE/B,KAAI,SACF,SAAQ,UAAU,SAAS;KAG3B,SAAQ,UAAU,KAAA,EAAoC;;;;;;;;;;AAY1D,SAAgB,iBAAoB,SAAsB,IAAgB;AACxE,KAAI,CAAC,kBAAkB,CAAC,QAAS,QAAO,IAAI;AAC5C,QAAO,QAAQ,IAAI,SAAS,GAAG;;;;;;;AAQjC,SAAgB,iBAAyC;CACvD,MAAM,OAAO,gBAAgB;AAC7B,KAAI,CAAC,KAAM,QAAO,EAAE;AACpB,QAAO;EACL,UAAU,KAAK;EACf,SAAS,KAAK;EACf"}