loggily 0.5.0 → 0.6.0

package/README.md

@@ -18,7 +18,7 @@ npm install loggily
 
 | Requirement   | Version                                           |
 | ------------- | ------------------------------------------------- |
-| Node.js       | 18+                                               |
+| Node.js       | >= 23.6                                           |
 | Bun           | 1.0+                                              |
 | TypeScript    | 5.2+ (for `using`; `.end()` works on any version) |
 | Module format | ESM-only                                          |

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-BDFU50FQ.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"}

package/dist/core-7D7sstHl.d.mts

@@ -0,0 +1,239 @@
+//#region src/core.d.ts
+/**
+ * loggily - Structured logging with spans
+ *
+ * Logger-first architecture: Span = Logger + Duration
+ *
+ * @example
+ * const log = createLogger('myapp')
+ *
+ * // Simple logging
+ * log.info('starting')
+ *
+ * // Lazy messages (function not called when level is disabled)
+ * log.debug?.(() => `expensive: ${computeState()}`)
+ *
+ * // Child loggers with context fields
+ * const reqLog = log.child({ requestId: 'abc' })
+ * reqLog.info('handling request')  // includes requestId in every message
+ *
+ * // With timing (span)
+ * {
+ *   using task = log.span('import', { file: 'data.csv' })
+ *   task.info('importing')
+ *   task.spanData.count = 42  // Set span attributes
+ *   // Auto-disposal on block exit → SPAN myapp:import (15ms)
+ * }
+ */
+/** Data passed to span recorders on disposal */
+interface SpanRecord {
+  readonly name: string;
+  readonly durationMs: number;
+}
+/** Interface for span duration recording — implemented by createMetricsCollector() in metrics.ts */
+interface SpanRecorder {
+  recordSpan(data: SpanRecord): void;
+}
+/**
+ * Ambient span recorder — auto-records when TRACE is active.
+ * Set by metrics.ts on import; can be replaced for testing.
+ * @internal
+ */
+declare let _ambientRecorder: SpanRecorder | null;
+declare function _setAmbientRecorder(recorder: SpanRecorder | null): void;
+/** Log levels that produce output */
+type OutputLogLevel = "trace" | "debug" | "info" | "warn" | "error";
+/** All log levels including silent (for filtering) */
+type LogLevel = OutputLogLevel | "silent";
+/** Message can be a string or a lazy function that returns a string */
+type LazyMessage = string | (() => string);
+/** Span props can be an object or a lazy function (skipped entirely via ?. when tracing is off) */
+type LazyProps = Record<string, unknown> | (() => Record<string, unknown>);
+/** Span data accessible via logger.spanData */
+interface SpanData {
+  readonly id: string;
+  readonly traceId: string;
+  readonly parentId: string | null;
+  readonly startTime: number;
+  readonly endTime: number | null;
+  readonly duration: number | null;
+  /** Custom attributes - set via direct property assignment */
+  [key: string]: unknown;
+}
+/** Logger interface */
+interface Logger {
+  /** Logger namespace (e.g., 'myapp:import') */
+  readonly name: string;
+  /** Props inherited from parent + own props */
+  readonly props: Readonly<Record<string, unknown>>;
+  /** Span data (non-null for span loggers, null for regular loggers) */
+  readonly spanData: SpanData | null;
+  trace(message: LazyMessage, data?: Record<string, unknown>): void;
+  debug(message: LazyMessage, data?: Record<string, unknown>): void;
+  info(message: LazyMessage, data?: Record<string, unknown>): void;
+  warn(message: LazyMessage, data?: Record<string, unknown>): void;
+  error(message: LazyMessage, data?: Record<string, unknown>): void;
+  /** Error overload - extracts message, stack, code from Error */
+  error(error: Error, data?: Record<string, unknown>): void;
+  /** Create child logger (extends namespace, inherits props) */
+  logger(namespace?: string, props?: Record<string, unknown>): Logger;
+  /** Create child span (extends namespace, inherits props, adds timing). Props can be lazy. */
+  span(namespace?: string, props?: LazyProps): SpanLogger;
+  /** Create child logger with context fields merged into every message */
+  child(context: Record<string, unknown>): Logger;
+  /** @deprecated Use .logger() instead for namespace-based children */
+  child(context: string): Logger;
+  /** End span manually (alternative to using keyword) */
+  end(): void;
+}
+/** Span logger - Logger with active span (spanData is non-null, implements Disposable) */
+interface SpanLogger extends Logger, Disposable {
+  readonly spanData: SpanData & {
+    /** Mutable attributes - set directly */[key: string]: unknown;
+  };
+}
+type LogWriter = (formatted: string, level: string) => void;
+/** Add a writer that receives all formatted log output. Returns unsubscribe. */
+declare function addWriter(writer: LogWriter): () => void;
+/** Suppress console output from the logger (writers still receive output). */
+declare function setSuppressConsole(value: boolean): void;
+/** Output mode for writeLog */
+type OutputMode = "console" | "stderr" | "writers-only";
+/** Set output mode for log messages (not spans — spans always use stderr). */
+declare function setOutputMode(mode: OutputMode): void;
+/** Get current output mode */
+declare function getOutputMode(): OutputMode;
+/** Set minimum log level */
+declare function setLogLevel(level: LogLevel): void;
+/** Get current log level */
+declare function getLogLevel(): LogLevel;
+/** Enable span output */
+declare function enableSpans(): void;
+/** Disable span output */
+declare function disableSpans(): void;
+/** Check if spans are enabled */
+declare function spansAreEnabled(): boolean;
+/**
+ * Set trace filter for namespace-based span output control.
+ * Only spans matching these namespace prefixes will be output.
+ * @param namespaces - Array of namespace prefixes, or null to disable filtering
+ */
+declare function setTraceFilter(namespaces: string[] | null): void;
+/** Get current trace filter (null means no filtering) */
+declare function getTraceFilter(): string[] | null;
+/**
+ * Set debug namespace filter (like the `debug` npm package).
+ * When set, only loggers matching these namespace prefixes produce output.
+ * Supports negative patterns with `-` prefix (e.g., ["-km:noisy"]).
+ * Also ensures log level is at least `debug`.
+ * @param namespaces - Array of namespace prefixes (prefix with `-` to exclude), or null to disable
+ */
+declare function setDebugFilter(namespaces: string[] | null): void;
+/** Get current debug namespace filter (null means no filtering) */
+declare function getDebugFilter(): string[] | null;
+/** Output format: human-readable console or structured JSON */
+type LogFormat = "console" | "json";
+/** Set log output format */
+declare function setLogFormat(format: LogFormat): void;
+/** Get current log output format */
+declare function getLogFormat(): LogFormat;
+declare function resetIds(): void;
+/**
+ * Register context propagation hooks (called by context.ts).
+ * @internal
+ */
+declare function _setContextHooks(hooks: {
+  getContextTags: () => Record<string, string>;
+  getContextParent: () => {
+    spanId: string;
+    traceId: string;
+  } | null;
+  enterContext: (spanId: string, traceId: string, parentId: string | null) => void;
+  exitContext: (spanId: string) => void;
+}): void;
+/**
+ * Clear context propagation hooks (called by disableContextPropagation).
+ * @internal
+ */
+declare function _clearContextHooks(): void;
+declare function writeSpan(namespace: string, duration: number, attrs: Record<string, unknown>): void;
+interface SpanDataFields {
+  id: string;
+  traceId: string;
+  parentId: string | null;
+  startTime: number;
+  endTime: number | null;
+  duration: number | null;
+}
+/**
+ * Create a proxy that exposes span metadata as readonly and custom attributes as writable.
+ * Shared between core logger spans and worker logger spans.
+ */
+declare function createSpanDataProxy(getFields: () => SpanDataFields, attrs: Record<string, unknown>): SpanData;
+/** Enable span collection for analysis */
+declare function startCollecting(): void;
+/** Stop collecting and return collected spans */
+declare function stopCollecting(): SpanData[];
+/** Get collected spans */
+declare function getCollectedSpans(): SpanData[];
+/** Clear collected spans */
+declare function clearCollectedSpans(): void;
+/**
+ * Logger with optional methods — returns undefined for disabled levels.
+ * Use with optional chaining: `log.debug?.("msg")` for zero-overhead when disabled.
+ *
+ * Defined as an explicit interface (not Omit<Logger,...>) so that
+ * oxlint's type-aware mode can resolve it without advanced type inference.
+ */
+interface ConditionalLogger {
+  readonly name: string;
+  readonly props: Readonly<Record<string, unknown>>;
+  readonly spanData: SpanData | null;
+  trace?: (message: LazyMessage, data?: Record<string, unknown>) => void;
+  debug?: (message: LazyMessage, data?: Record<string, unknown>) => void;
+  info?: (message: LazyMessage, data?: Record<string, unknown>) => void;
+  warn?: (message: LazyMessage, data?: Record<string, unknown>) => void;
+  error?: {
+    (message: LazyMessage, data?: Record<string, unknown>): void;
+    (error: Error, data?: Record<string, unknown>): void;
+  };
+  logger(namespace?: string, props?: Record<string, unknown>): Logger;
+  span(namespace?: string, props?: LazyProps): SpanLogger;
+  child(context: Record<string, unknown>): Logger;
+  child(context: string): Logger;
+  end(): void;
+}
+/**
+ * Create a logger for a component.
+ * Returns undefined for disabled levels - use with optional chaining for zero overhead.
+ *
+ * Log levels (most → least verbose): trace < debug < info < warn < error < silent
+ * Default level: info (trace and debug disabled)
+ *
+ * @example
+ * const log = createLogger('myapp')
+ *
+ * // All methods support ?. for zero-overhead when disabled
+ * log.trace?.(`very verbose: ${expensiveDebug()}`)  // Skipped at info level
+ * log.debug?.(`debug: ${getState()}`)               // Skipped at info level
+ * log.info?.('starting')                            // Enabled at info level
+ * log.warn?.('deprecated')                          // Enabled at info level
+ * log.error?.('failed')                             // Enabled at info level
+ *
+ * // With -q flag or LOG_LEVEL=warn:
+ * log.info?.('starting')  // Now skipped - info < warn
+ *
+ * // With initial props
+ * const log = createLogger('myapp', { version: '1.0' })
+ *
+ * // Create spans
+ * {
+ *   using task = log.span('import', { file: 'data.csv' })
+ *   task.info?.('importing')
+ *   task.spanData.count = 42
+ * }
+ */
+declare function createLogger(name: string, props?: Record<string, unknown>): ConditionalLogger;
+//#endregion
+export { setDebugFilter as A, getCollectedSpans as C, getOutputMode as D, getLogLevel as E, setTraceFilter as F, spansAreEnabled as I, startCollecting as L, setLogLevel as M, setOutputMode as N, getTraceFilter as O, setSuppressConsole as P, stopCollecting as R, enableSpans as S, getLogFormat as T, addWriter as _, LogLevel as a, createSpanDataProxy as b, OutputMode as c, SpanRecord as d, SpanRecorder as f, _setContextHooks as g, _setAmbientRecorder as h, LogFormat as i, setLogFormat as j, resetIds as k, SpanData as l, _clearContextHooks as m, LazyMessage as n, Logger as o, _ambientRecorder as p, LazyProps as r, OutputLogLevel as s, ConditionalLogger as t, SpanLogger as u, clearCollectedSpans as v, getDebugFilter as w, disableSpans as x, createLogger as y, writeSpan as z };
+//# sourceMappingURL=core-7D7sstHl.d.mts.map

package/dist/core-7D7sstHl.d.mts.map

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