loggily 0.6.2 → 0.8.0

package/dist/core-B3pox577.mjs

@@ -0,0 +1,1074 @@
+import { createMetricsCollector, withMetrics } from "./metrics.mjs";
+import { closeSync, openSync, writeSync } from "node:fs";
+//#region src/colors.ts
+/**
+* Vendored ANSI color functions — replaces picocolors dependency.
+* Supports NO_COLOR, FORCE_COLOR, and TTY detection.
+*/
+const _process$1 = typeof process !== "undefined" ? process : void 0;
+const enabled = _process$1?.env?.["FORCE_COLOR"] !== void 0 && _process$1?.env?.["FORCE_COLOR"] !== "0" ? true : _process$1?.env?.["NO_COLOR"] !== void 0 ? false : _process$1?.stdout?.isTTY ?? false;
+function wrap(open, close) {
+	if (!enabled) return (str) => str;
+	return (str) => open + str + close;
+}
+const colors = {
+	dim: wrap("\x1B[2m", "\x1B[22m"),
+	blue: wrap("\x1B[34m", "\x1B[39m"),
+	yellow: wrap("\x1B[33m", "\x1B[39m"),
+	red: wrap("\x1B[31m", "\x1B[39m"),
+	magenta: wrap("\x1B[35m", "\x1B[39m"),
+	cyan: wrap("\x1B[36m", "\x1B[39m")
+};
+//#endregion
+//#region src/file-writer.ts
+/**
+* File writer for loggily — Node.js/Bun only.
+*
+* Separated from core logger to allow tree-shaking in browser bundles.
+* Uses dynamic import("node:fs") to avoid static dependency on Node APIs.
+*/
+/**
+* Create an async buffered file writer for log output.
+* Buffers writes and flushes on size threshold or interval.
+* Registers a process.on('exit') handler to flush remaining buffer.
+*
+* **Node.js/Bun only** — not available in browser environments.
+*
+* @param filePath - Path to the log file (opened in append mode)
+* @param options - Buffer size and flush interval configuration
+* @returns FileWriter with write, flush, and close methods
+*
+* @example
+* const writer = createFileWriter('/tmp/app.log')
+* const unsubscribe = addWriter((formatted) => writer.write(formatted))
+*
+* // On shutdown:
+* unsubscribe()
+* writer.close()
+*/
+function createFileWriter(filePath, options = {}) {
+	const bufferSize = options.bufferSize ?? 4096;
+	const flushInterval = options.flushInterval ?? 100;
+	let buffer = "";
+	let fd = null;
+	let timer = null;
+	let closed = false;
+	fd = openSync(filePath, "a");
+	/** Flush buffer contents to disk synchronously */
+	function flush() {
+		if (buffer.length === 0 || fd === null) return;
+		writeSync(fd, buffer);
+		buffer = "";
+	}
+	timer = setInterval(flush, flushInterval);
+	if (timer && typeof timer === "object" && "unref" in timer) timer.unref();
+	const exitHandler = () => flush();
+	process.on("exit", exitHandler);
+	return {
+		write(line) {
+			if (closed) return;
+			buffer += line + "\n";
+			if (buffer.length >= bufferSize) flush();
+		},
+		flush,
+		close() {
+			if (closed) return;
+			closed = true;
+			if (timer !== null) {
+				clearInterval(timer);
+				timer = null;
+			}
+			try {
+				flush();
+			} catch {} finally {
+				if (fd !== null) {
+					closeSync(fd);
+					fd = null;
+				}
+				process.removeListener("exit", exitHandler);
+			}
+		}
+	};
+}
+//#endregion
+//#region src/tracing.ts
+let currentIdFormat = "simple";
+/**
+* Set the ID format for new spans and traces.
+* - "simple": sp_1, sp_2, tr_1, tr_2 (default, lightweight)
+* - "w3c": 32-char hex trace ID, 16-char hex span ID (W3C Trace Context compatible)
+*
+* @deprecated Use the `TRACE_ID_FORMAT` env var or `{ idFormat: "w3c" }` in the config array instead.
+*/
+function setIdFormat(format) {
+	currentIdFormat = format;
+}
+/**
+* Get the current ID format.
+*
+* @deprecated Use the `TRACE_ID_FORMAT` env var or `{ idFormat: "w3c" }` in the config array instead.
+*/
+function getIdFormat() {
+	return currentIdFormat;
+}
+let simpleSpanCounter = 0;
+let simpleTraceCounter = 0;
+/** Generate a hex string of the given byte length using crypto.randomUUID */
+function randomHex(bytes) {
+	return crypto.randomUUID().replace(/-/g, "").slice(0, bytes * 2);
+}
+/** Generate a span ID according to the current format */
+function generateSpanId() {
+	if (currentIdFormat === "w3c") return randomHex(8);
+	return `sp_${(++simpleSpanCounter).toString(36)}`;
+}
+/** Generate a trace ID according to the current format */
+function generateTraceId() {
+	if (currentIdFormat === "w3c") return randomHex(16);
+	return `tr_${(++simpleTraceCounter).toString(36)}`;
+}
+/** Reset ID counters (for testing) */
+function resetIdCounters() {
+	simpleSpanCounter = 0;
+	simpleTraceCounter = 0;
+}
+/**
+* Format a W3C traceparent header from span data.
+*
+* Format: `{version}-{trace-id}-{span-id}-{trace-flags}`
+* - version: "00" (current W3C spec version)
+* - trace-id: 32 hex chars (128 bits)
+* - span-id: 16 hex chars (64 bits)
+* - trace-flags: "01" (sampled) or "00" (not sampled)
+*
+* Works with both simple and W3C ID formats. Simple IDs are zero-padded to spec length.
+*
+* @param spanData - Span data with id and traceId
+* @param options - Optional settings (sampled flag). Defaults to sampled=true.
+* @returns W3C traceparent header string
+*
+* @example
+* ```typescript
+* const span = log.span("http-request")
+* const header = traceparent(span.spanData)
+* // → "00-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6-1a2b3c4d5e6f7a8b-01"
+* fetch(url, { headers: { traceparent: header } })
+* ```
+*/
+function traceparent(spanData, options) {
+	return `00-${padHex(spanData.traceId, 32)}-${padHex(spanData.id, 16)}-${options?.sampled ?? true ? "01" : "00"}`;
+}
+/** Pad or hash an ID to the specified hex length */
+function padHex(id, length) {
+	if (id.length === length && /^[0-9a-f]+$/.test(id)) return id;
+	let hex = "";
+	for (let i = 0; i < id.length; i++) hex += id.charCodeAt(i).toString(16).padStart(2, "0");
+	return hex.padStart(length, "0").slice(-length);
+}
+let sampleRate = 1;
+/**
+* Set the head-based sampling rate for new traces.
+* Applied at trace creation — all spans within a sampled trace are kept.
+*
+* @deprecated Use the `TRACE_SAMPLE_RATE` env var or `{ sampleRate: 0.1 }` in the config array instead.
+* @param rate - Sampling rate from 0.0 (sample nothing) to 1.0 (sample everything, default)
+*/
+function setSampleRate(rate) {
+	if (rate < 0 || rate > 1) throw new Error(`Sample rate must be between 0.0 and 1.0, got ${rate}`);
+	sampleRate = rate;
+}
+/**
+* Get the current sampling rate.
+*
+* @deprecated Use the `TRACE_SAMPLE_RATE` env var or `{ sampleRate: 0.1 }` in the config array instead.
+*/
+function getSampleRate() {
+	return sampleRate;
+}
+/**
+* Determine whether a new trace should be sampled.
+* Called at trace creation time (head-based sampling).
+*/
+function shouldSample() {
+	if (sampleRate >= 1) return true;
+	if (sampleRate <= 0) return false;
+	return Math.random() < sampleRate;
+}
+//#endregion
+//#region src/pipeline.ts
+const LOG_LEVEL_PRIORITY = {
+	trace: 0,
+	debug: 1,
+	info: 2,
+	warn: 3,
+	error: 4,
+	silent: 5
+};
+const _process = typeof process !== "undefined" ? process : void 0;
+function getEnv(key) {
+	return _process?.env?.[key];
+}
+function writeStderr(text) {
+	if (_process?.stderr?.write) _process.stderr.write(text + "\n");
+	else console.error(text);
+}
+/** Serialize Error.cause chains up to a max depth */
+function serializeCause(cause, maxDepth = 3) {
+	if (maxDepth <= 0 || cause === void 0 || cause === null) return void 0;
+	if (cause instanceof Error) {
+		const result = {
+			name: cause.name,
+			message: cause.message,
+			stack: cause.stack
+		};
+		if (cause.code) result.code = cause.code;
+		if (cause.cause !== void 0) result.cause = serializeCause(cause.cause, maxDepth - 1);
+		return result;
+	}
+	return cause;
+}
+function safeStringify(value) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	return JSON.stringify(value, (_key, val) => {
+		if (typeof val === "bigint") return val.toString();
+		if (typeof val === "symbol") return val.toString();
+		if (val instanceof Error) {
+			const result = {
+				message: val.message,
+				stack: val.stack,
+				name: val.name
+			};
+			if (val.code) result.code = val.code;
+			if (val.cause !== void 0) result.cause = serializeCause(val.cause);
+			return result;
+		}
+		if (typeof val === "object" && val !== null) {
+			if (seen.has(val)) return "[Circular]";
+			seen.add(val);
+		}
+		return val;
+	});
+}
+function formatConsoleEvent(event) {
+	const time = colors.dim(new Date(event.time).toISOString().split("T")[1]?.split(".")[0] || "");
+	const ns = colors.cyan(event.namespace);
+	if (event.kind === "span") {
+		const message = `(${event.duration}ms)`;
+		let output = `${time} ${colors.magenta("SPAN")} ${ns} ${message}`;
+		if (event.props && Object.keys(event.props).length > 0) output += ` ${colors.dim(safeStringify(event.props))}`;
+		return output;
+	}
+	let levelStr;
+	switch (event.level) {
+		case "trace":
+			levelStr = colors.dim("TRACE");
+			break;
+		case "debug":
+			levelStr = colors.dim("DEBUG");
+			break;
+		case "info":
+			levelStr = colors.blue("INFO");
+			break;
+		case "warn":
+			levelStr = colors.yellow("WARN");
+			break;
+		case "error":
+			levelStr = colors.red("ERROR");
+			break;
+	}
+	let output = `${time} ${levelStr} ${ns} ${event.message}`;
+	if (event.props && Object.keys(event.props).length > 0) output += ` ${colors.dim(safeStringify(event.props))}`;
+	return output;
+}
+function formatJSONEvent(event) {
+	if (event.kind === "span") return safeStringify({
+		time: new Date(event.time).toISOString(),
+		level: "span",
+		name: event.namespace,
+		msg: `(${event.duration}ms)`,
+		duration: event.duration,
+		span_id: event.spanId,
+		trace_id: event.traceId,
+		parent_id: event.parentId,
+		...event.props
+	});
+	return safeStringify({
+		time: new Date(event.time).toISOString(),
+		level: event.level,
+		name: event.namespace,
+		msg: event.message,
+		...event.props
+	});
+}
+function matchesPattern(namespace, pattern) {
+	if (pattern === "*") return true;
+	if (pattern.endsWith(":*")) {
+		const prefix = pattern.slice(0, -2);
+		return namespace === prefix || namespace.startsWith(prefix + ":");
+	}
+	return namespace === pattern || namespace.startsWith(pattern + ":");
+}
+function parseNsFilter(ns) {
+	const patterns = typeof ns === "string" ? ns.split(",").map((s) => s.trim()) : ns;
+	const includes = [];
+	const excludes = [];
+	for (const p of patterns) if (p.startsWith("-")) excludes.push(p.slice(1));
+	else includes.push(p);
+	return (namespace) => {
+		for (const exc of excludes) if (matchesPattern(namespace, exc)) return false;
+		if (includes.length > 0) {
+			for (const inc of includes) if (matchesPattern(namespace, inc)) return true;
+			return false;
+		}
+		return true;
+	};
+}
+/**
+* Write formatted text to console using the appropriate log level.
+*
+* IMPORTANT: We use Function.bind() to preserve caller source locations in
+* browser DevTools. When you click a log line in DevTools, it shows where
+* YOUR code called log.info?.(), not where pipeline.ts called console.info().
+* DO NOT replace bind() with direct console.info(text) calls — it breaks
+* source location tracking in browsers.
+*/
+function writeToConsole(text, event) {
+	if (event.kind === "span") {
+		writeStderr(text);
+		return;
+	}
+	switch (event.level) {
+		case "trace":
+		case "debug":
+			Function.prototype.bind.call(console.debug, console, text)();
+			break;
+		case "info":
+			Function.prototype.bind.call(console.info, console, text)();
+			break;
+		case "warn":
+			Function.prototype.bind.call(console.warn, console, text)();
+			break;
+		case "error":
+			Function.prototype.bind.call(console.error, console, text)();
+			break;
+	}
+}
+function createConsoleSink(format) {
+	const formatter = format === "json" ? formatJSONEvent : formatConsoleEvent;
+	return (event) => writeToConsole(formatter(event), event);
+}
+function createFileSink(path, format) {
+	const writer = createFileWriter(path);
+	const formatter = format === "json" ? formatJSONEvent : formatConsoleEvent;
+	return {
+		write: (event) => writer.write(formatter(event)),
+		dispose: () => writer.close()
+	};
+}
+function isNodeStream(obj) {
+	return typeof obj === "object" && obj !== null && ("_write" in obj || "writable" in obj || "fd" in obj);
+}
+function createWritableSink(writable, format) {
+	if (!(writable.objectMode ?? !isNodeStream(writable))) {
+		const formatter = format === "json" ? formatJSONEvent : formatConsoleEvent;
+		return (event) => writable.write(formatter(event) + "\n");
+	}
+	return (event) => writable.write(event);
+}
+const VALID_CONFIG_KEYS = new Set([
+	"level",
+	"ns",
+	"format",
+	"spans",
+	"metrics",
+	"idFormat",
+	"sampleRate"
+]);
+const SINK_KEYS = new Set(["file", "otel"]);
+function isPojo(obj) {
+	if (typeof obj !== "object" || obj === null) return false;
+	const proto = Object.getPrototypeOf(obj);
+	return proto === Object.prototype || proto === null;
+}
+function isWritable(obj) {
+	return typeof obj === "object" && obj !== null && "write" in obj && typeof obj.write === "function";
+}
+function isValidLogLevel(val) {
+	return typeof val === "string" && val in LOG_LEVEL_PRIORITY;
+}
+function buildPipeline(elements, parentConfig) {
+	const config = {
+		level: parentConfig?.level ?? readEnvLevel(),
+		ns: parentConfig?.ns ?? readEnvNs(),
+		format: parentConfig?.format ?? readEnvFormat()
+	};
+	let spansEnabled = true;
+	const stages = [];
+	const outputs = [];
+	const branches = [];
+	const disposables = [];
+	for (const element of elements) {
+		if (Array.isArray(element)) {
+			const branch = buildPipeline(element, { ...config });
+			branches.push(branch);
+			disposables.push(() => branch.dispose());
+			continue;
+		}
+		if (element === console || element === "console") {
+			outputs.push({
+				levelPriority: LOG_LEVEL_PRIORITY[config.level],
+				nsFilter: config.ns,
+				write: createConsoleSink(config.format)
+			});
+			continue;
+		}
+		if (typeof element === "function") {
+			stages.push(element);
+			continue;
+		}
+		if (isWritable(element)) {
+			outputs.push({
+				levelPriority: LOG_LEVEL_PRIORITY[config.level],
+				nsFilter: config.ns,
+				write: createWritableSink(element, config.format)
+			});
+			continue;
+		}
+		if (isPojo(element)) {
+			const obj = element;
+			const keys = Object.keys(obj);
+			const hasSinkKey = keys.some((k) => SINK_KEYS.has(k));
+			if (keys.some((k) => !VALID_CONFIG_KEYS.has(k) && !SINK_KEYS.has(k))) {
+				const unknown = keys.find((k) => !VALID_CONFIG_KEYS.has(k) && !SINK_KEYS.has(k));
+				throw new Error(`loggily: unknown config key "${unknown}" in config object. Valid keys: ${[...VALID_CONFIG_KEYS, ...SINK_KEYS].join(", ")}`);
+			}
+			if (hasSinkKey) {
+				if (typeof obj.file === "string") {
+					const outputLevel = isValidLogLevel(obj.level) ? obj.level : config.level;
+					const outputNs = obj.ns ? parseNsFilter(obj.ns) : config.ns;
+					const outputFormat = obj.format ?? config.format;
+					const sink = createFileSink(obj.file, outputFormat);
+					disposables.push(sink.dispose);
+					outputs.push({
+						levelPriority: LOG_LEVEL_PRIORITY[outputLevel],
+						nsFilter: outputNs,
+						write: sink.write,
+						dispose: sink.dispose
+					});
+				}
+				if (obj.otel !== void 0) throw new Error("loggily: OTEL sink is not yet implemented. See loggily/otel for the planned bridge.");
+				continue;
+			}
+			if (isValidLogLevel(obj.level)) config.level = obj.level;
+			if (obj.ns !== void 0) config.ns = parseNsFilter(obj.ns);
+			if (obj.format === "console" || obj.format === "json") config.format = obj.format;
+			if (obj.spans === true) spansEnabled = true;
+			if (obj.spans === false) spansEnabled = false;
+			if (obj.idFormat === "simple" || obj.idFormat === "w3c") setIdFormat(obj.idFormat);
+			if (typeof obj.sampleRate === "number") setSampleRate(obj.sampleRate);
+			continue;
+		}
+		if (element === "stderr" && typeof process !== "undefined") {
+			outputs.push({
+				levelPriority: LOG_LEVEL_PRIORITY[config.level],
+				nsFilter: config.ns,
+				write: createWritableSink(process.stderr, config.format)
+			});
+			continue;
+		}
+		throw new Error(`loggily: unsupported config element of type "${typeof element}". Config arrays accept: objects (config), arrays (branches), functions (stages), console, "console", or writables ({ write }).`);
+	}
+	const dispatch = (event) => {
+		if (event.kind === "span" && !spansEnabled) return;
+		let e = event;
+		for (const stage of stages) {
+			const result = stage(e);
+			if (result === null) return;
+			if (result !== void 0) e = result;
+		}
+		for (const output of outputs) {
+			if (e.kind === "log" && LOG_LEVEL_PRIORITY[e.level] < output.levelPriority) continue;
+			if (output.nsFilter && !output.nsFilter(e.namespace)) continue;
+			output.write(e);
+		}
+		for (const branch of branches) branch.dispatch(e);
+	};
+	return {
+		dispatch,
+		level: config.level,
+		dispose: () => {
+			for (const d of disposables) d();
+		}
+	};
+}
+function readEnvLevel() {
+	const env = getEnv("LOG_LEVEL")?.toLowerCase();
+	let level = env === "trace" || env === "debug" || env === "info" || env === "warn" || env === "error" || env === "silent" ? env : "info";
+	if (getEnv("DEBUG") && LOG_LEVEL_PRIORITY[level] > LOG_LEVEL_PRIORITY.debug) level = "debug";
+	return level;
+}
+/**
+* Namespace-aware level: only bumps to debug if the namespace matches the DEBUG filter.
+* This enables zero-overhead conditional gating — `log.debug?.()` returns undefined
+* for namespaces outside the DEBUG filter, skipping argument evaluation entirely.
+*/
+function readEnvLevelForNamespace(namespace) {
+	const env = getEnv("LOG_LEVEL")?.toLowerCase();
+	const baseLevel = env === "trace" || env === "debug" || env === "info" || env === "warn" || env === "error" || env === "silent" ? env : "info";
+	if (getEnv("DEBUG") && LOG_LEVEL_PRIORITY[baseLevel] > LOG_LEVEL_PRIORITY.debug) {
+		const nsFilter = readEnvNs();
+		if (nsFilter && nsFilter(namespace)) return "debug";
+		return baseLevel;
+	}
+	return baseLevel;
+}
+function readEnvNs() {
+	const debugEnv = getEnv("DEBUG");
+	if (!debugEnv) return null;
+	return parseNsFilter(debugEnv.split(",").map((s) => s.trim()));
+}
+function readEnvFormat() {
+	const envFormat = getEnv("LOG_FORMAT")?.toLowerCase();
+	if (envFormat === "json") return "json";
+	if (envFormat === "console") return "console";
+	if (getEnv("TRACE_FORMAT") === "json") return "json";
+	if (getEnv("NODE_ENV") === "production") return "json";
+	return "console";
+}
+function readEnvTrace() {
+	const traceEnv = getEnv("TRACE");
+	if (!traceEnv) return {
+		enabled: false,
+		filter: null
+	};
+	if (traceEnv === "1" || traceEnv === "true") return {
+		enabled: true,
+		filter: null
+	};
+	const prefixes = traceEnv.split(",").map((s) => s.trim());
+	return {
+		enabled: true,
+		filter: (namespace) => {
+			for (const prefix of prefixes) if (matchesPattern(namespace, prefix)) return true;
+			return false;
+		}
+	};
+}
+//#endregion
+//#region src/core.ts
+/**
+* loggily v2 — Structured logging with spans
+*
+* One import. Objects configure. Arrays branch. Values write.
+*
+* @example
+* const log = createLogger('myapp')
+* log.info?.('starting')
+*
+* @example
+* const log = createLogger('myapp', [
+*   { level: 'debug', ns: '-sql' },
+*   console,
+*   { file: '/tmp/app.log', level: 'info', format: 'json' },
+* ])
+* log.info?.('server started', { port: 3000 })
+*/
+function resetIds() {
+	resetIdCounters();
+}
+let _getContextTags = null;
+let _getContextParent = null;
+let _enterContext = null;
+let _exitContext = null;
+/** @internal */
+function _setContextHooks(hooks) {
+	_getContextTags = hooks.getContextTags;
+	_getContextParent = hooks.getContextParent;
+	_enterContext = hooks.enterContext;
+	_exitContext = hooks.exitContext;
+}
+/** @internal */
+function _clearContextHooks() {
+	_getContextTags = null;
+	_getContextParent = null;
+	_enterContext = null;
+	_exitContext = null;
+}
+function createSpanDataProxy(getFields, attrs) {
+	const READONLY_KEYS = new Set([
+		"id",
+		"traceId",
+		"parentId",
+		"startTime",
+		"endTime",
+		"duration"
+	]);
+	return new Proxy(attrs, {
+		get(_target, prop) {
+			if (READONLY_KEYS.has(prop)) return getFields()[prop];
+			return attrs[prop];
+		},
+		set(_target, prop, value) {
+			if (READONLY_KEYS.has(prop)) return false;
+			attrs[prop] = value;
+			return true;
+		}
+	});
+}
+const collectedSpans = [];
+let collectSpans = false;
+function startCollecting() {
+	collectSpans = true;
+	collectedSpans.length = 0;
+}
+function stopCollecting() {
+	collectSpans = false;
+	return [...collectedSpans];
+}
+function getCollectedSpans() {
+	return [...collectedSpans];
+}
+function clearCollectedSpans() {
+	collectedSpans.length = 0;
+}
+function resolveMessage(msg) {
+	return typeof msg === "function" ? msg() : msg;
+}
+function createLoggerImpl(name, props, pipeline) {
+	const emitLog = (level, msgOrError, dataOrMsg, extraData) => {
+		let message;
+		let data;
+		if (msgOrError instanceof Error) {
+			const err = msgOrError;
+			const contextTags = _getContextTags?.() ?? {};
+			if (typeof dataOrMsg === "string") {
+				message = dataOrMsg;
+				data = {
+					...contextTags,
+					...props,
+					...extraData,
+					error_type: err.name,
+					error_message: err.message,
+					error_stack: err.stack,
+					error_code: err.code,
+					error_cause: err.cause !== void 0 ? serializeCause(err.cause) : void 0
+				};
+			} else {
+				message = err.message;
+				data = {
+					...contextTags,
+					...props,
+					...dataOrMsg,
+					error_type: err.name,
+					error_stack: err.stack,
+					error_code: err.code,
+					error_cause: err.cause !== void 0 ? serializeCause(err.cause) : void 0
+				};
+			}
+		} else {
+			message = resolveMessage(msgOrError);
+			const contextTags = _getContextTags?.();
+			data = contextTags && Object.keys(contextTags).length > 0 ? {
+				...contextTags,
+				...props,
+				...dataOrMsg
+			} : Object.keys(props).length > 0 || dataOrMsg ? {
+				...props,
+				...dataOrMsg
+			} : void 0;
+		}
+		const event = {
+			kind: "log",
+			time: Date.now(),
+			namespace: name,
+			level,
+			message,
+			props: data
+		};
+		pipeline.dispatch(event);
+	};
+	return {
+		name,
+		props: Object.freeze({ ...props }),
+		get level() {
+			return pipeline.level;
+		},
+		dispatch(event) {
+			pipeline.dispatch(event);
+		},
+		[Symbol.dispose]() {
+			pipeline.dispose();
+		},
+		trace: (msg, data) => emitLog("trace", msg, data),
+		debug: (msg, data) => emitLog("debug", msg, data),
+		info: (msg, data) => emitLog("info", msg, data),
+		warn: (msg, data) => emitLog("warn", msg, data),
+		error: (msgOrError, dataOrMsg, extraData) => emitLog("error", msgOrError, dataOrMsg, extraData),
+		logger(namespace, childProps) {
+			return this.child(namespace ?? "", childProps);
+		},
+		span(_namespace, _childProps) {
+			throw new Error("loggily: span() requires the withSpans() plugin. Use pipe(baseCreateLogger, withSpans()) or the default createLogger.");
+		},
+		child(namespaceOrContext, childProps) {
+			if (typeof namespaceOrContext === "string") return wrapConditional(createLoggerImpl(namespaceOrContext ? `${name}:${namespaceOrContext}` : name, {
+				...props,
+				...childProps
+			}, pipeline), () => pipeline.level);
+			return wrapConditional(createLoggerImpl(name, {
+				...props,
+				...namespaceOrContext
+			}, pipeline), () => pipeline.level);
+		},
+		end() {}
+	};
+}
+function wrapConditional(logger, getLevel) {
+	return new Proxy(logger, { get(target, prop) {
+		if (typeof prop === "string" && prop in LOG_LEVEL_PRIORITY && prop !== "silent") {
+			if (LOG_LEVEL_PRIORITY[prop] < LOG_LEVEL_PRIORITY[getLevel()]) return;
+		}
+		if (prop === "span") {
+			const val = target[prop];
+			if (val === baseSpanStub) return void 0;
+			return val;
+		}
+		return target[prop];
+	} });
+}
+const baseSpanStub = function baseSpanStub(_namespace, _childProps) {
+	throw new Error("loggily: span() requires the withSpans() plugin. Use pipe(baseCreateLogger, withSpans()) or the default createLogger.");
+};
+/**
+* Plugin: adds span creation capability to loggers.
+* Without this plugin, `.span` is undefined on ConditionalLogger.
+* Included by default in `createLogger`.
+*/
+function withSpans() {
+	return (factory, _ctx) => {
+		return (name, configOrProps) => {
+			return augmentWithSpans(factory(name, configOrProps), null, null, true);
+		};
+	};
+}
+function augmentWithSpans(logger, parentSpanId, traceId, traceSampled) {
+	const spanState = {
+		parentSpanId,
+		traceId,
+		traceSampled
+	};
+	return new Proxy(logger, { get(target, prop) {
+		if (prop === "span") return createSpanMethod(target, spanState);
+		if (prop === "child") return function child(namespaceOrContext, childProps) {
+			return augmentWithSpans(target.child(namespaceOrContext, childProps), spanState.parentSpanId, spanState.traceId, spanState.traceSampled);
+		};
+		if (prop === "logger") return function logger(namespace, childProps) {
+			return augmentWithSpans(target.logger(namespace, childProps), spanState.parentSpanId, spanState.traceId, spanState.traceSampled);
+		};
+		return target[prop];
+	} });
+}
+function createSpanMethod(logger, spanState) {
+	return (namespace, childProps) => {
+		const childName = namespace ? `${logger.name}:${namespace}` : logger.name;
+		const resolvedChildProps = typeof childProps === "function" ? childProps() : childProps;
+		const mergedProps = {
+			...logger.props,
+			...resolvedChildProps
+		};
+		const newSpanId = generateSpanId();
+		let resolvedParentId = spanState.parentSpanId;
+		let resolvedTraceId = spanState.traceId;
+		if (!resolvedParentId && _getContextParent) {
+			const ctxParent = _getContextParent();
+			if (ctxParent) {
+				resolvedParentId = ctxParent.spanId;
+				resolvedTraceId = resolvedTraceId || ctxParent.traceId;
+			}
+		}
+		const isNewTrace = !resolvedTraceId;
+		const finalTraceId = resolvedTraceId || generateTraceId();
+		const sampled = isNewTrace ? shouldSample() : spanState.traceSampled;
+		const newSpanData = {
+			id: newSpanId,
+			traceId: finalTraceId,
+			parentId: resolvedParentId,
+			startTime: Date.now(),
+			endTime: null,
+			duration: null,
+			attrs: {}
+		};
+		const spanAugmented = augmentWithSpans(logger.child(namespace ?? "", resolvedChildProps), newSpanId, finalTraceId, sampled);
+		_enterContext?.(newSpanId, finalTraceId, resolvedParentId);
+		const disposeSpan = () => {
+			if (newSpanData.endTime !== null) return;
+			newSpanData.endTime = Date.now();
+			newSpanData.duration = newSpanData.endTime - newSpanData.startTime;
+			if (collectSpans) collectedSpans.push(createSpanDataProxy(() => ({
+				id: newSpanData.id,
+				traceId: newSpanData.traceId,
+				parentId: newSpanData.parentId,
+				startTime: newSpanData.startTime,
+				endTime: newSpanData.endTime,
+				duration: newSpanData.duration
+			}), { ...newSpanData.attrs }));
+			_exitContext?.(newSpanId);
+			if (sampled) {
+				const spanEvent = {
+					kind: "span",
+					time: newSpanData.endTime,
+					namespace: childName,
+					name: childName,
+					duration: newSpanData.duration,
+					props: {
+						...mergedProps,
+						...newSpanData.attrs
+					},
+					spanId: newSpanData.id,
+					traceId: newSpanData.traceId,
+					parentId: newSpanData.parentId
+				};
+				logger.dispatch(spanEvent);
+			}
+		};
+		const spanDataProxy = createSpanDataProxy(() => ({
+			id: newSpanData.id,
+			traceId: newSpanData.traceId,
+			parentId: newSpanData.parentId,
+			startTime: newSpanData.startTime,
+			endTime: newSpanData.endTime,
+			duration: newSpanData.endTime !== null ? newSpanData.endTime - newSpanData.startTime : Date.now() - newSpanData.startTime
+		}), newSpanData.attrs);
+		let currentDispose = disposeSpan;
+		return new Proxy(spanAugmented, {
+			get(target, prop) {
+				if (prop === "spanData") return spanDataProxy;
+				if (prop === Symbol.dispose) return currentDispose;
+				if (prop === "end") return () => {
+					if (newSpanData.endTime === null) currentDispose();
+				};
+				if (prop === "name") return childName;
+				if (prop === "props") return Object.freeze({ ...mergedProps });
+				return target[prop];
+			},
+			set(_target, prop, value) {
+				if (prop === Symbol.dispose) {
+					currentDispose = value;
+					return true;
+				}
+				return false;
+			}
+		});
+	};
+}
+/**
+* Base createLogger — requires a config array.
+* Use the default `createLogger` export (with `withEnvDefaults`) for zero-config.
+*
+* Note: loggers from baseCreateLogger do NOT have `.span()` capability.
+* Use `pipe(baseCreateLogger, withSpans())` or the default `createLogger` for spans.
+*/
+function baseCreateLogger(name, configOrProps) {
+	let pipeline;
+	let props = {};
+	if (Array.isArray(configOrProps)) pipeline = buildPipeline(configOrProps);
+	else if (configOrProps && typeof configOrProps === "object") {
+		props = configOrProps;
+		pipeline = buildPipeline(["console"]);
+	} else pipeline = buildPipeline(["console"]);
+	const logger = createLoggerImpl(name, props, pipeline);
+	logger.span = baseSpanStub;
+	return wrapConditional(logger, () => pipeline.level);
+}
+function pipe(base, ...plugins) {
+	const ctx = {};
+	return plugins.reduce((factory, plugin) => plugin(factory, ctx), base);
+}
+const _env = (typeof process !== "undefined" ? process : void 0)?.env ?? {};
+function currentLevel() {
+	return readEnvLevel();
+}
+function currentNs() {
+	return readEnvNs();
+}
+function currentFormat() {
+	return readEnvFormat();
+}
+function currentTrace() {
+	return readEnvTrace();
+}
+const _writers = [];
+let _suppressConsole = false;
+let _logFileWriterFactory = null;
+/** @internal */
+function _setLogFileWriterFactory(factory) {
+	_logFileWriterFactory = factory;
+}
+/**
+* Plugin: read defaults from environment variables (LOG_LEVEL, DEBUG, LOG_FORMAT, TRACE, LOG_FILE).
+* Included by default. Omit to disable env-var behavior entirely.
+*
+* When no config array is given, provides console output + env-var-based config.
+* When a config array IS given, env vars are already used as defaults by buildPipeline.
+* Legacy setters (setLogLevel, addWriter, etc.) affect loggers created without explicit config.
+*/
+function withEnvDefaults() {
+	return (factory, _ctx) => (name, configOrProps) => {
+		const envIdFormat = _env.TRACE_ID_FORMAT?.toLowerCase();
+		if (envIdFormat === "simple" || envIdFormat === "w3c") setIdFormat(envIdFormat);
+		const envSampleRate = _env.TRACE_SAMPLE_RATE;
+		if (envSampleRate !== void 0) {
+			const rate = Number.parseFloat(envSampleRate);
+			if (!Number.isNaN(rate) && rate >= 0 && rate <= 1) setSampleRate(rate);
+		}
+		if (Array.isArray(configOrProps)) return factory(name, configOrProps);
+		const envPipeline = createEnvPipeline();
+		const envStage = (event) => {
+			envPipeline.dispatch(event);
+			return null;
+		};
+		if (configOrProps && typeof configOrProps === "object") return applyNamespaceGating(factory(name, [{ level: "trace" }, envStage]).child(configOrProps));
+		return applyNamespaceGating(factory(name, [{ level: "trace" }, envStage]));
+	};
+}
+/**
+* Wrap a logger so that conditional method gating is namespace-aware.
+* When DEBUG=myapp:db, only loggers whose namespace matches get debug enabled.
+* Without this, all loggers get debug because readEnvLevel() bumps globally.
+*/
+function applyNamespaceGating(logger) {
+	return new Proxy(logger, { get(target, prop) {
+		if (typeof prop === "string" && prop in LOG_LEVEL_PRIORITY && prop !== "silent") {
+			const nsLevel = readEnvLevelForNamespace(target.name);
+			if (LOG_LEVEL_PRIORITY[prop] < LOG_LEVEL_PRIORITY[nsLevel]) return;
+		}
+		return target[prop];
+	} });
+}
+function createEnvPipeline() {
+	const disposables = [];
+	const logFile = _env.LOG_FILE;
+	let fileSink = null;
+	if (logFile && _logFileWriterFactory) {
+		const writer = _logFileWriterFactory(logFile);
+		fileSink = (event) => {
+			const fmt = currentFormat() === "json" ? formatJSONEvent : formatConsoleEvent;
+			writer.write(fmt(event));
+		};
+		disposables.push(() => writer.close());
+	}
+	const dispatch = (event) => {
+		if (event.kind === "log" && LOG_LEVEL_PRIORITY[event.level] < LOG_LEVEL_PRIORITY[currentLevel()]) return;
+		if (event.kind === "span") {
+			const trace = currentTrace();
+			if (!trace.enabled) return;
+			if (trace.filter && !trace.filter(event.namespace)) return;
+		}
+		const ns = currentNs();
+		if (ns && !ns(event.namespace)) return;
+		const text = (currentFormat() === "json" ? formatJSONEvent : formatConsoleEvent)(event);
+		const lvl = event.kind === "log" ? event.level : "span";
+		for (const w of _writers) w(text, lvl);
+		if (!_suppressConsole) writeToConsole(text, event);
+		fileSink?.(event);
+	};
+	return {
+		dispatch,
+		get level() {
+			return currentLevel();
+		},
+		dispose: () => {
+			for (const d of disposables) d();
+		}
+	};
+}
+/**
+* Plugin: when `{ metrics: true }` appears in the config array, automatically
+* creates a MetricsCollector and applies withMetrics to the logger.
+* The collector is accessible via `logger.metrics`.
+*/
+function withConfigMetrics() {
+	return (factory, _ctx) => {
+		return (name, configOrProps) => {
+			const logger = factory(name, configOrProps);
+			if (!Array.isArray(configOrProps)) return logger;
+			if (!configOrProps.some((el) => typeof el === "object" && el !== null && !Array.isArray(el) && "metrics" in el && el.metrics === true)) return logger;
+			return withMetrics(createMetricsCollector())(logger);
+		};
+	};
+}
+/** Default createLogger — includes withEnvDefaults + withSpans + withConfigMetrics. */
+const createLogger = pipe(baseCreateLogger, withEnvDefaults(), withSpans(), withConfigMetrics());
+/** Test helper — all levels, console output. */
+function createTestLogger(name) {
+	return pipe(baseCreateLogger, withSpans())(name, [{ level: "trace" }, "console"]);
+}
+/** @deprecated Use config array */
+function setLogLevel(level) {
+	_env.LOG_LEVEL = level;
+}
+function getLogLevel() {
+	return currentLevel();
+}
+function enableSpans() {
+	_env.TRACE = "1";
+}
+function disableSpans() {
+	delete _env.TRACE;
+}
+function spansAreEnabled() {
+	return !!_env.TRACE;
+}
+function setTraceFilter(namespaces) {
+	if (!namespaces || namespaces.length === 0) delete _env.TRACE;
+	else _env.TRACE = namespaces.join(",");
+}
+function getTraceFilter() {
+	return _env.TRACE ? _env.TRACE.split(",") : null;
+}
+function setDebugFilter(namespaces) {
+	if (!namespaces || namespaces.length === 0) delete _env.DEBUG;
+	else _env.DEBUG = namespaces.join(",");
+}
+function getDebugFilter() {
+	return _env.DEBUG ? _env.DEBUG.split(",") : null;
+}
+function setLogFormat(format) {
+	_env.LOG_FORMAT = format;
+}
+function getLogFormat() {
+	return currentFormat();
+}
+function setSuppressConsole(value) {
+	_suppressConsole = value;
+}
+function setOutputMode(_mode) {
+	throw new Error("loggily: setOutputMode() is removed in v2. Use config arrays: omit console from array for writers-only, use \"stderr\" for stderr mode.");
+}
+function getOutputMode() {
+	return "console";
+}
+function addWriter(writer) {
+	_writers.push(writer);
+	return () => {
+		const i = _writers.indexOf(writer);
+		if (i !== -1) _writers.splice(i, 1);
+	};
+}
+function writeSpan(namespace, duration, attrs) {
+	createEnvPipeline().dispatch({
+		kind: "span",
+		time: Date.now(),
+		namespace,
+		name: namespace,
+		duration,
+		props: attrs,
+		spanId: attrs.span_id ?? "",
+		traceId: attrs.trace_id ?? "",
+		parentId: attrs.parent_id ?? null
+	});
+}
+//#endregion
+export { withEnvDefaults as A, setSampleRate as B, setOutputMode as C, startCollecting as D, spansAreEnabled as E, safeStringify as F, createFileWriter as H, serializeCause as I, getIdFormat as L, writeSpan as M, LOG_LEVEL_PRIORITY as N, stopCollecting as O, buildPipeline as P, getSampleRate as R, setLogLevel as S, setTraceFilter as T, traceparent as V, getTraceFilter as _, baseCreateLogger as a, setDebugFilter as b, createSpanDataProxy as c, enableSpans as d, getCollectedSpans as f, getOutputMode as g, getLogLevel as h, addWriter as i, withSpans as j, withConfigMetrics as k, createTestLogger as l, getLogFormat as m, _setContextHooks as n, clearCollectedSpans as o, getDebugFilter as p, _setLogFileWriterFactory as r, createLogger as s, _clearContextHooks as t, disableSpans as u, pipe as v, setSuppressConsole as w, setLogFormat as x, resetIds as y, setIdFormat as z };
+
+//# sourceMappingURL=core-B3pox577.mjs.map