loggily 0.8.0 → 0.10.0

package/README.md

@@ -1,266 +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 (colors don't render on GitHub -- run it in a terminal):
-
-```
-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 `?.`
+**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)
 
-Disabled logs should not build strings, serialize objects, or compute snapshots just to throw them away.
+## Getting Started
 
-With most loggers, this work still happens:
+```console
+$ npm install loggily
 
-```typescript
-log.debug(`state: ${JSON.stringify(computeExpensiveState())}`)
-// computeExpensiveState() runs even when debug is off
+$ 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
 ```
 
-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
-```
-
-In benchmarks with expensive disabled log arguments, this is [~22x faster](https://loggily.dev/guide/benchmarks) than a conventional noop logger.
-
-## 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                |
-
-Loggily uses `Symbol.dispose` (TC39 Explicit Resource Management) for span cleanup, which requires a modern runtime.
-
-## Features
-
-- **Zero-cost disabled logs** -- `?.` short-circuits the entire call: no string interpolation, no JSON.stringify, no function evaluation. [~22x faster](https://loggily.dev/guide/benchmarks) than noop loggers.
-- **Config pipeline** -- `createLogger("app", [config, console, { file }, stage, [branch]])`. Objects configure, arrays branch, values write.
-- **Namespace hierarchy** -- `DEBUG=myapp:db` shows only database output. Same patterns as the `debug` package.
-- **Spans** -- `using span = log.span("name")`. Duration, parent-child tracking, trace IDs, custom data. Control per-pipeline with `{ spans: true/false }`.
-- **Dev & production** -- colorized console in development, structured JSON in production. Same code.
-- **Child loggers** -- `log.child("auth")` extends namespace, `log.child({ requestId })` adds context.
-- **Async context** -- `AsyncLocalStorage` propagation: every log in a request's async chain inherits trace/span IDs automatically.
-- **Error cause chains** -- `log.error?.(err)` serializes `Error.cause` recursively (up to 3 levels).
-- **Worker threads** -- pipeline-based: `createWorkerLogger(postMessage, "ns")` on worker, `createWorkerLogHandler()` on main. Same events, same pipeline.
-- **OpenTelemetry bridge** -- `toOtel({ api })` stage forwards events to any OTLP backend. Transparent: events pass through to subsequent pipeline elements.
-- **Pino transport compatible** -- works with object-mode writable sinks (compatible with Pino transport interface). Events use Loggily's record shape.
-- **Span metrics** -- `{ metrics: true }` in config auto-creates a collector on `log.metrics` (p50/p95/p99). Or use `withMetrics(collector)` for shared/custom collectors.
-- **Head-based sampling** -- `setSampleRate(0.1)` to sample 10% of traces.
-- **Composable plugins** -- `pipe(baseCreateLogger, withSpans(), myPlugin())` to build custom factories.
-- **Browser support** -- bundlers auto-select the browser entry point via `browser` condition.
-- **~3 KB, zero dependencies.**
-
-## Quick Start
-
 ```typescript
 import { createLogger } from "loggily"
+import { toOtel } from "loggily/otel"
 
-const log = createLogger("myapp", [{ level: "debug" }, console])
+// Config pipeline — objects configure, arrays branch, values write
+const log = createLogger("myapp", [
+  { 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
+])
 
+// Structured logging
 log.info?.("server started", { port: 3000 })
-log.debug?.("cache hit", { key: "user:42" })
-log.error?.(new Error("timeout"), "request failed", { url: "/api" })
+log.debug?.(`state: ${expensiveFunc()}`) // skipped if debug off
+log.error?.(new Error("connection lost"))
 
-// Child loggers
+// Child loggers — extend namespace, add context
 const dbLog = log.child("db", { pool: "main" }) // namespace: "myapp:db"
 
-// Spans -- time any operation
+// Spans — time any operation, auto-track parent/child + trace IDs
+// AsyncLocalStorage propagation: logs in async chains inherit span context
 {
-  using span = dbLog.span("query", { table: "users" })
-  const users = await queryUsers() // your DB call
-  span.spanData.count = users.length
+  using span = dbLog.span?.("query", { table: "users" })
+  const users = await queryUsers() // logs inside queryUsers() get trace IDs
+  if (span) span.spanData.count = users.length
 }
 // → SPAN myapp:db:query (45ms) {count: 100, table: "users"}
-```
 
-## Complete Example
+// Metrics — p50/p95/p99 from spans
+log.metrics.summary() // myapp:db:query: 42 spans, mean=3.2ms, p95=8.4ms
 
-The config array accepts six element types -- here they are in one pipeline:
-
-```typescript
-import { createLogger } from "loggily"
-import { toOtel } from "loggily/otel"
-import * as otelApi from "@opentelemetry/api"
-
-const log = createLogger("myapp", [
-  // "myapp" -- namespace, filter with DEBUG=myapp
-  { level: "debug", metrics: true }, // config object -- sets scope
-  toOtel({ api: otelApi }), // stage -- transforms/forwards events
-  pinoTransport, // writable -- { write } receives raw Events
-  { file: "/tmp/app.log", format: "json" }, // file sink -- writes formatted strings
-  [{ level: "error" }, { file: "/tmp/err.log" }], // branch -- sub-pipeline with own scope
-  console, // console -- colorized, human-readable
-])
-
-// Custom writable -- any { write } receives raw Event objects
-const log2 = createLogger("ingest", [
-  { write: (event) => fetch("/ingest", { method: "POST", body: JSON.stringify(event) }) },
-  console,
-])
-
-// Custom stage -- functions transform, filter, or enrich events
-const log3 = createLogger("filtered", [
-  (event) => (event.kind === "log" && event.message.includes("secret") ? null : event),
-  (event) => ({ ...event, props: { ...event.props, host: os.hostname() } }),
-  console,
-])
-
-// Metrics -- { metrics: true } auto-creates a collector on log.metrics
-for (const [name, s] of log.metrics.all()) {
-  if (s.p95 > 100) console.warn(`${name} is slow: p95=${s.p95}ms`)
-}
-```
-
-### Composition with plugins
-
-`createLogger` is `pipe(baseCreateLogger, withEnvDefaults(), withSpans(), withConfigMetrics())`. For full manual control:
-
-```typescript
-import { baseCreateLogger, pipe, withSpans, withEnvDefaults } from "loggily"
-
-// Custom factory — choose exactly which plugins to include
+// Composable — build custom factories
 const myCreateLogger = pipe(baseCreateLogger, withSpans(), myPlugin())
-const log = myCreateLogger("myapp", [console])
-```
-
-`baseCreateLogger` does NOT include `withSpans()` or `withEnvDefaults()` — loggers it creates cannot create spans and do not read environment variables.
-
-### Test helper
-
-```typescript
-import { createTestLogger } from "loggily"
-const log = createTestLogger("test") // all levels enabled, console output
 ```
 
-### Environment variables
-
-| Variable            | Values                                  | Default   |
-| ------------------- | --------------------------------------- | --------- |
-| `LOG_LEVEL`         | trace, debug, info, warn, error, silent | `info`    |
-| `LOG_FORMAT`        | console, json                           | `console` |
-| `LOG_FILE`          | file path                               | (none)    |
-| `DEBUG`             | `*`, namespace prefixes, `-prefix`      | (none)    |
-| `TRACE`             | `1`, `true`, namespace prefixes         | (none)    |
-| `TRACE_FORMAT`      | json                                    | (none)    |
-| `TRACE_ID_FORMAT`   | simple, w3c                             | `simple`  |
-| `TRACE_SAMPLE_RATE` | 0.0 -- 1.0                              | `1.0`     |
-| `NODE_ENV`          | production                              | (none)    |
-
-### Namespace filter patterns
-
-| Pattern            | Matches                                                        |
-| ------------------ | -------------------------------------------------------------- |
-| `*`                | Everything                                                     |
-| `myapp`            | Exact match + children (`myapp`, `myapp:db`, `myapp:db:query`) |
-| `myapp:*`          | Same as `myapp` — explicit wildcard                            |
-| `-myapp:sql`       | Exclude `myapp:sql` and its children                           |
-| `myapp,-myapp:sql` | Include myapp, exclude sql subtree                             |
-
-### Types
-
-Key types exported for power users:
-
-| 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                              |
-| `ConfigElement`     | Union of all valid config array elements                         |
-| `ConfigObject`      | Scope config: `{ level?, ns?, format?, spans? }`                 |
-| `FileDescriptor`    | File output: `{ file, level?, ns?, format? }`                    |
-| `Writable`          | Any object with `{ write, objectMode? }`                         |
-
-`buildPipeline()` is exported for direct pipeline construction.
-
-### Subpath exports
-
-| Import path       | Contents                                                             |
-| ----------------- | -------------------------------------------------------------------- |
-| `loggily`         | Core API, types, pipeline builder                                    |
-| `loggily/context` | AsyncLocalStorage context propagation (Node.js)                      |
-| `loggily/worker`  | Worker thread logger + message handlers                              |
-| `loggily/otel`    | OpenTelemetry bridge (`toOtel` stage)                                |
-| `loggily/metrics` | Span metrics collection (`{ metrics: true }` or explicit collectors) |
-
-## Compatibility & Destinations
-
-- **OpenTelemetry** -- `toOtel({ api })` forwards to Jaeger, Grafana, Datadog, or any OTLP backend
-- **Sentry** -- capture errors via a 3-line stage function
-- **Pino transports** -- works with object-mode writable sinks (compatible with Pino transport interface)
-- **Elasticsearch / OpenSearch** -- post JSON events directly
-- **AWS CloudWatch** -- writable calling `putLogEvents`
-- **Prometheus** -- expose `log.metrics` as a `/metrics` endpoint
-- **`DEBUG=` patterns** -- same namespace filter syntax as the `debug` package
-- **W3C Trace Context** -- `traceparent()` generates standard headers
-- **Browser** -- bundlers auto-select the browser entry point
-- **Worker threads** -- pipeline-based forwarding via `postMessage`
-
-See the [Destinations guide](https://loggily.dev/guide/destinations) for copy-paste recipes.
-
-## Why this exists
-
-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 auto-instrumentation** (HTTP, database, gRPC). Use OpenTelemetry's SDK directly -- Loggily's OTEL bridge forwards events but doesn't instrument frameworks.
-- **You need log rotation, file compression, or dozens of transport plugins.** Pino's transport ecosystem is deeper. (You can use Pino transports with Loggily's `objectMode` writables, but Pino owns that ecosystem.)
-- **You're not on a modern runtime.** Loggily requires Node.js >= 23.6 or Bun >= 1.0.
+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://loggily.dev/guide/journey)** -- progressive guide from first log to full observability
-- **[Full docs site](https://loggily.dev/)** -- guides, API reference, migration guides
-- [Comparison](https://loggily.dev/guide/comparison) -- what Loggily does, compatibility, when to use something else
-- [Migration from debug](https://loggily.dev/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 { n as _setContextHooks, t as _clearContextHooks } from "./core-B3pox577.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"}