loggily 0.6.2 → 0.8.0

package/README.md

@@ -2,28 +2,28 @@
 
 **Clarity without the clutter.**
 
-Debugs, logs, and spans — one API.
+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 like Pino for production, and ad-hoc timers or a tracing SDK for performance. Three APIs, three configs, three output formats.
+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 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])
 
 log.info?.("server started", { port: 3000 })
 log.debug?.("cache hit", { key: "user:42" })
 log.error?.(new Error("connection lost"))
 ```
 
-Readable, colorized output in development:
+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}
@@ -55,7 +55,7 @@ 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.
+In benchmarks with expensive disabled log arguments, this is [~22x faster](https://loggily.dev/guide/benchmarks) than a conventional noop logger.
 
 ## Install
 
@@ -63,52 +63,184 @@ In benchmarks with expensive disabled log arguments, this is [~22x faster](https
 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 |
+| Requirement   | Version                                         |
+| ------------- | ----------------------------------------------- |
+| Node.js       | >= 23.6                                         |
+| Bun           | 1.0+                                            |
+| TypeScript    | 5.2+ for `using`; `.end()` works on any version |
+| Module format | ESM-only                                        |
+| Browser       | Supported via conditional export                |
 
 Loggily uses `Symbol.dispose` (TC39 Explicit Resource Management) for span cleanup, which requires a modern runtime.
 
 ## Features
 
-- **Namespace hierarchy** — organize logs with `:` separators. `DEBUG=myapp:db` shows only database output, just like the `debug` package.
-- **Lightweight spans** — time any operation with `using span = log.span("name")`. Automatic duration, parent-child tracking, and trace IDs.
-- **Dev & production** — colorized console in development, structured JSON in production. Same code, zero config.
-- **Child context** — `log.child({ requestId })` adds structured fields to every message in the chain.
-- **Automatic async context** — enable `AsyncLocalStorage`-based propagation and every log in a request's async chain inherits trace/span IDs without passing loggers around.
-- **Lazy messages** — `log.debug?.(() => expensiveString())` skips the function entirely when disabled.
-- **File writer** — `addWriter()` + `createFileWriter()` for buffered file output.
-- **Worker threads** — forward logs from workers to the main thread with full type safety.
-
-### Spans
+- **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"
+
+const log = createLogger("myapp", [{ level: "debug" }, console])
+
+log.info?.("server started", { port: 3000 })
+log.debug?.("cache hit", { key: "user:42" })
+log.error?.(new Error("timeout"), "request failed", { url: "/api" })
+
+// Child loggers
+const dbLog = log.child("db", { pool: "main" }) // namespace: "myapp:db"
+
+// Spans -- time any operation
 {
-  using span = log.span("db:query", { table: "users" })
-  const users = await db.query("SELECT * FROM users")
+  using span = dbLog.span("query", { table: "users" })
+  const users = await queryUsers() // your DB call
   span.spanData.count = users.length
 }
-// SPAN myapp:db:query (45ms) {count: 100, table: "users"}
+// → SPAN myapp:db:query (45ms) {count: 100, table: "users"}
+```
 
-// Without `using` — call .end() manually
-const span = log.span("db:query")
-try { /* ... */ } finally { span.end() }
+## Complete Example
+
+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`)
+}
 ```
 
-### Common configuration
+### Composition with plugins
+
+`createLogger` is `pipe(baseCreateLogger, withEnvDefaults(), withSpans(), withConfigMetrics())`. For full manual control:
 
-| Variable | Example | Effect |
-|---|---|---|
-| `DEBUG` | `myapp:db,-myapp:sql` | Namespace filter (same syntax as the `debug` package) |
-| `LOG_LEVEL` | `debug`, `info`, `warn` | Minimum output level |
-| `LOG_FORMAT` | `console`, `json` | Override output format |
-| `TRACE` | `1` or namespace prefixes | Enable span output |
+```typescript
+import { baseCreateLogger, pipe, withSpans, withEnvDefaults } from "loggily"
+
+// Custom factory — choose exactly which plugins to include
+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
+```
 
-See the [full environment variable reference](https://beorn.codes/loggily/api/configuration).
+### 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
 
@@ -118,15 +250,16 @@ Loggily was built while developing a terminal UI where disabled debug logs insid
 
 ## When not to use Loggily
 
-- **You need the absolute fastest structured logger with a transport ecosystem.** Use [Pino](https://getpino.io/) for worker-thread transports, custom serializers, and log rotation.
-- **You need distributed tracing with vendor exporters and auto-instrumentation.** Use [OpenTelemetry](https://opentelemetry.io/).
+- **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.
 
 ## 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
+- **[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
 
 ## 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 { n as _setContextHooks, t as _clearContextHooks } from "./core-B3pox577.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"}