loggily 0.6.1 → 0.7.0

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 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")
+const log = createLogger("myapp", [{ level: "debug" }, console])
 
-// ?. 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,108 +31,144 @@ 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 `?.`
+
+Disabled logs should not build strings, serialize objects, or compute snapshots just to throw them away.
 
-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:
+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
+```
+
+In benchmarks with expensive disabled log arguments, this is [~22x faster](https://beorn.codes/loggily/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
+
+- **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"
+
+// Objects configure, arrays branch, values write
+const log = createLogger("myapp", [
+  { level: "debug", ns: "-sql" },
+  console,
+  { file: "/tmp/app.log", level: "error", format: "json" },
+])
+```
+
+When no config array is provided, loggily reads `LOG_LEVEL`, `DEBUG`, `LOG_FORMAT`, and `NODE_ENV` from the environment.
+
+### Spans
 
 ```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"}
+// SPAN myapp:db:query (45ms) {count: 100, table: "users"}
 
-// Without `using` — works on any runtime
-const span = log.span("db:query", { table: "users" })
+// Without `using` — call .end() manually
+const span = log.span("db:query")
 try {
-  const users = await db.query("SELECT * FROM users")
-  span.spanData.count = users.length
+  /* ... */
 } finally {
   span.end()
 }
 ```
 
-## Why Loggily?
+### Common configuration
 
-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.
+| 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                                     |
 
-### Near-zero cost for disabled logs
+See the [full environment variable reference](https://beorn.codes/loggily/api/configuration).
 
-Most loggers waste work when logging is disabled. Even with a noop function, arguments are still evaluated:
+### Types
 
-```typescript
-// Traditional — args are ALWAYS evaluated, even when debug is off
-log.debug(`state: ${JSON.stringify(computeExpensiveState())}`)
-```
+Key types exported for power users:
 
-Loggily uses optional chaining to skip the entire call — including argument evaluation:
+| 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                              |
 
-```typescript
-// Loggily — args are NOT evaluated when disabled
-log.debug?.(`state: ${JSON.stringify(computeExpensiveState())}`)
-```
+`buildPipeline()` and `defaultPipeline()` are exported for direct pipeline construction.
 
-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.
+## Compatibility
 
-> **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.
+- **`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`
 
-## Features
+## 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.
 
-- **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).
+> **Status:** Early release (0.x). The core API is stable, but details may evolve before 1.0.
 
-## When Not to Use Loggily
+## When not to use Loggily
 
-- **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.
+- **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.
 
 ## Documentation
 
-- **[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) — 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.
+- **[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
 
 ## License
 

package/dist/context.d.mts

@@ -0,0 +1,91 @@
+//#region src/context.d.ts
+/**
+ * AsyncLocalStorage-based context propagation for loggily — Node.js/Bun only.
+ *
+ * Separated from core logger to allow tree-shaking in browser bundles.
+ * When enabled, new spans automatically parent to the current context span,
+ * and writeLog() auto-tags with trace_id/span_id from context.
+ *
+ * @example
+ * ```typescript
+ * import { enableContextPropagation, getCurrentSpan } from "loggily/context"
+ *
+ * enableContextPropagation()
+ *
+ * const log = createLogger("myapp")
+ * {
+ *   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
+ *
+ *   const current = getCurrentSpan()
+ *   // current === { spanId: "sp_1", traceId: "tr_1", parentId: null }
+ * }
+ * ```
+ */
+/** Minimal span context stored in AsyncLocalStorage */
+interface SpanContext {
+  readonly spanId: string;
+  readonly traceId: string;
+  readonly parentId: string | null;
+}
+/**
+ * Enable AsyncLocalStorage-based context propagation.
+ * Once enabled, new spans automatically parent to the current context span,
+ * and log messages are auto-tagged with trace_id/span_id.
+ *
+ * **Node.js/Bun only** — not available in browser environments.
+ */
+declare function enableContextPropagation(): void;
+/**
+ * Disable context propagation.
+ * Existing spans continue to work, but new spans won't auto-parent.
+ */
+declare function disableContextPropagation(): void;
+/** Check if context propagation is enabled */
+declare function isContextPropagationEnabled(): boolean;
+/**
+ * Get the current span context from AsyncLocalStorage.
+ * Returns null if no span is active in the current async context,
+ * or if context propagation is not enabled.
+ */
+declare function getCurrentSpan(): SpanContext | null;
+/**
+ * Enter a span context for the remainder of the current synchronous execution
+ * and any async operations started from it. Used by the logger when creating
+ * spans with `using` — since `using` doesn't wrap user code in a callback,
+ * `enterWith()` is the right primitive.
+ *
+ * Captures the full previous SpanContext snapshot so it can be restored
+ * exactly on exit, even with non-LIFO end() ordering.
+ *
+ * @internal
+ */
+declare function enterSpanContext(spanId: string, traceId: string, parentId: string | null): void;
+/**
+ * Restore the previous span context (called when a span ends).
+ * Restores the exact SpanContext snapshot captured at enter time,
+ * preventing corruption from non-LIFO end() ordering.
+ *
+ * @internal
+ */
+declare function exitSpanContext(spanId: string): void;
+/**
+ * Run a function within a span context.
+ * Used for explicit context scoping (e.g., in request handlers).
+ *
+ * @param context - The span context to set
+ * @param fn - The function to run within the context
+ * @returns The return value of fn
+ */
+declare function runInSpanContext<T>(context: SpanContext, fn: () => T): T;
+/**
+ * Get the context tags (trace_id, span_id) for the current async context.
+ * Used by writeLog() to auto-tag log messages.
+ * Returns empty object if context propagation is disabled or no span is active.
+ */
+declare function getContextTags(): Record<string, string>;
+//#endregion
+export { SpanContext, disableContextPropagation, enableContextPropagation, enterSpanContext, exitSpanContext, getContextTags, getCurrentSpan, isContextPropagationEnabled, runInSpanContext };
+//# sourceMappingURL=context.d.mts.map

package/dist/context.d.mts.map

@@ -0,0 +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"}

package/dist/context.mjs

@@ -0,0 +1,145 @@
+import { i as _setContextHooks, n as _clearContextHooks } from "./core-Du3sIje6.mjs";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/context.ts
+/**
+* AsyncLocalStorage-based context propagation for loggily — Node.js/Bun only.
+*
+* Separated from core logger to allow tree-shaking in browser bundles.
+* When enabled, new spans automatically parent to the current context span,
+* and writeLog() auto-tags with trace_id/span_id from context.
+*
+* @example
+* ```typescript
+* import { enableContextPropagation, getCurrentSpan } from "loggily/context"
+*
+* enableContextPropagation()
+*
+* const log = createLogger("myapp")
+* {
+*   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
+*
+*   const current = getCurrentSpan()
+*   // current === { spanId: "sp_1", traceId: "tr_1", parentId: null }
+* }
+* ```
+*/
+let storage = null;
+let contextEnabled = false;
+/**
+* Map from spanId → the SpanContext that was active when the span was entered.
+* Used to restore the exact previous context on exit, avoiding corruption
+* from non-LIFO end() ordering.
+*/
+const previousContexts = /* @__PURE__ */ new Map();
+/**
+* Enable AsyncLocalStorage-based context propagation.
+* Once enabled, new spans automatically parent to the current context span,
+* and log messages are auto-tagged with trace_id/span_id.
+*
+* **Node.js/Bun only** — not available in browser environments.
+*/
+function enableContextPropagation() {
+	if (!storage) storage = new AsyncLocalStorage();
+	contextEnabled = true;
+	_setContextHooks({
+		getContextTags,
+		getContextParent() {
+			const span = getCurrentSpan();
+			if (!span) return null;
+			return {
+				spanId: span.spanId,
+				traceId: span.traceId
+			};
+		},
+		enterContext: enterSpanContext,
+		exitContext: exitSpanContext
+	});
+}
+/**
+* Disable context propagation.
+* Existing spans continue to work, but new spans won't auto-parent.
+*/
+function disableContextPropagation() {
+	contextEnabled = false;
+	_clearContextHooks();
+}
+/** Check if context propagation is enabled */
+function isContextPropagationEnabled() {
+	return contextEnabled;
+}
+/**
+* Get the current span context from AsyncLocalStorage.
+* Returns null if no span is active in the current async context,
+* or if context propagation is not enabled.
+*/
+function getCurrentSpan() {
+	if (!contextEnabled || !storage) return null;
+	return storage.getStore() ?? null;
+}
+/**
+* Enter a span context for the remainder of the current synchronous execution
+* and any async operations started from it. Used by the logger when creating
+* spans with `using` — since `using` doesn't wrap user code in a callback,
+* `enterWith()` is the right primitive.
+*
+* Captures the full previous SpanContext snapshot so it can be restored
+* exactly on exit, even with non-LIFO end() ordering.
+*
+* @internal
+*/
+function enterSpanContext(spanId, traceId, parentId) {
+	if (!contextEnabled || !storage) return;
+	const previous = storage.getStore() ?? null;
+	previousContexts.set(spanId, previous);
+	storage.enterWith({
+		spanId,
+		traceId,
+		parentId
+	});
+}
+/**
+* Restore the previous span context (called when a span ends).
+* Restores the exact SpanContext snapshot captured at enter time,
+* preventing corruption from non-LIFO end() ordering.
+*
+* @internal
+*/
+function exitSpanContext(spanId) {
+	if (!contextEnabled || !storage) return;
+	const previous = previousContexts.get(spanId);
+	previousContexts.delete(spanId);
+	if (previous) storage.enterWith(previous);
+	else storage.enterWith(void 0);
+}
+/**
+* Run a function within a span context.
+* Used for explicit context scoping (e.g., in request handlers).
+*
+* @param context - The span context to set
+* @param fn - The function to run within the context
+* @returns The return value of fn
+*/
+function runInSpanContext(context, fn) {
+	if (!contextEnabled || !storage) return fn();
+	return storage.run(context, fn);
+}
+/**
+* Get the context tags (trace_id, span_id) for the current async context.
+* Used by writeLog() to auto-tag log messages.
+* Returns empty object if context propagation is disabled or no span is active.
+*/
+function getContextTags() {
+	const span = getCurrentSpan();
+	if (!span) return {};
+	return {
+		trace_id: span.traceId,
+		span_id: span.spanId
+	};
+}
+//#endregion
+export { disableContextPropagation, enableContextPropagation, enterSpanContext, exitSpanContext, getContextTags, getCurrentSpan, isContextPropagationEnabled, runInSpanContext };
+
+//# sourceMappingURL=context.mjs.map

package/dist/context.mjs.map

@@ -0,0 +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"}