loggily 0.8.0 → 0.10.1

package/dist/{core-B3pox577.mjs → core-DKwMMOZw.mjs}

@@ -49,15 +49,21 @@ const colors = {
 function createFileWriter(filePath, options = {}) {
 	const bufferSize = options.bufferSize ?? 4096;
 	const flushInterval = options.flushInterval ?? 100;
+	const fs = options.__fs ?? {
+		openSync,
+		writeSync,
+		closeSync
+	};
 	let buffer = "";
 	let fd = null;
 	let timer = null;
 	let closed = false;
-	fd = openSync(filePath, "a");
+	fd = fs.openSync(filePath, "a");
 	/** Flush buffer contents to disk synchronously */
 	function flush() {
 		if (buffer.length === 0 || fd === null) return;
-		writeSync(fd, buffer);
+		const data = buffer;
+		fs.writeSync(fd, data);
 		buffer = "";
 	}
 	timer = setInterval(flush, flushInterval);
@@ -82,7 +88,7 @@ function createFileWriter(filePath, options = {}) {
 				flush();
 			} catch {} finally {
 				if (fd !== null) {
-					closeSync(fd);
+					fs.closeSync(fd);
 					fd = null;
 				}
 				process.removeListener("exit", exitHandler);
@@ -149,7 +155,8 @@ function resetIdCounters() {
 *
 * @example
 * ```typescript
-* const span = log.span("http-request")
+* const span = log.span?.("http-request")
+* if (!span) return
 * const header = traceparent(span.spanData)
 * // → "00-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6-1a2b3c4d5e6f7a8b-01"
 * fetch(url, { headers: { traceparent: header } })
@@ -195,6 +202,211 @@ function shouldSample() {
 	return Math.random() < sampleRate;
 }
 //#endregion
+//#region src/console-sinks.ts
+/**
+* Console sinks — runtime-aware structured output to console.
+*
+* Two sinks, one contract: `(event: Event) => void`. They do NOT pre-format
+* events into a single ANSI string. Instead they spread structured arguments
+* to `console.*` so the platform can render rich output:
+*
+*   Terminal (Node / Bun):
+*     console.info(ansiPrefix, message, ...userArgs)
+*     — util.format keeps objects inspectable in devtools
+*
+*   Browser (Chrome / Firefox / Safari DevTools):
+*     console.info("%c<level> %c<namespace>", levelCss, nsCss, message, ...userArgs)
+*     — DevTools renders colored prefix and keeps every user arg as an
+*       expandable, clickable object.
+*
+* Source-location preservation:
+* We call `console.<level>(...)` from arrow-function sinks. DevTools attribute
+* the log line to the caller's frame, not this file, as long as no wrapper
+* closes over a bound console reference. `Function.prototype.bind.call(console.info, ...)`
+* works too but defeats `vi.spyOn(console, 'info')` because bind captures
+* the function at bind time. Plain arrow functions re-read `console.info`
+* on each call — mockable AND location-preserving.
+*
+* The sinks consume `event.userArgs` (raw user-supplied data/errors) when
+* present, falling back to `event.props` so they still work with code paths
+* that have not yet been migrated.
+*/
+/**
+* True when running inside a browser-like environment. We check for the
+* presence of a `window` with `document` — the Node DOM test env (jsdom)
+* also matches, but that is the correct behaviour for DevTools-style output.
+*/
+function isBrowserRuntime() {
+	return typeof globalThis?.window !== "undefined" && typeof globalThis.document !== "undefined";
+}
+function timeStr(time) {
+	return new Date(time).toISOString().split("T")[1]?.split(".")[0] ?? "";
+}
+function levelLabel(level) {
+	switch (level) {
+		case "trace": return "TRACE";
+		case "debug": return "DEBUG";
+		case "info": return "INFO";
+		case "warn": return "WARN";
+		case "error": return "ERROR";
+	}
+}
+/**
+* Return the raw user-supplied data attached to the event, in call order.
+* Prefers the explicit `userArgs` field (new path). Falls back to `props`
+* (coerced to a single trailing object) for events emitted by older code or
+* by `writeSpan`. Filters out `undefined` entries.
+*/
+function userArgsOf(event) {
+	if ("userArgs" in event && Array.isArray(event.userArgs)) return event.userArgs.filter((v) => v !== void 0);
+	if (event.props && Object.keys(event.props).length > 0) return [event.props];
+	return [];
+}
+/**
+* Terminal (ANSI) sink. Emits `[ansiPrefix, message, ...userArgs]` so that:
+*   - stdout gets a colored prefix
+*   - util.format leaves objects inspectable
+*   - vi.spyOn(console, 'info') intercepts calls (arrows re-read console)
+*
+* Spans and JSON format still go through the pre-formatted single-arg path —
+* their consumers are log aggregators, not humans.
+*/
+function createTerminalConsoleSink(format = "console") {
+	if (format === "json") return (event) => routeSingle(event, formatJSONEvent(event));
+	return (event) => {
+		if (event.kind === "span") {
+			writeStderrLine(formatConsoleEvent(event));
+			return;
+		}
+		const prefix = `${colors.dim(timeStr(event.time))} ${levelAnsi(event.level)} ${colors.cyan(event.namespace)}`;
+		const args = userArgsOf(event);
+		invokeForLevel(event.level, prefix, event.message, ...args);
+	};
+}
+/** Emit one line to process.stderr when available (no-op in browser). */
+function writeStderrLine(text) {
+	const p = typeof process !== "undefined" ? process : void 0;
+	if (p?.stderr && typeof p.stderr.write === "function") {
+		p.stderr.write(text + "\n");
+		return;
+	}
+	console.info(text);
+}
+function levelAnsi(level) {
+	switch (level) {
+		case "trace": return colors.dim("TRACE");
+		case "debug": return colors.dim("DEBUG");
+		case "info": return colors.blue("INFO");
+		case "warn": return colors.yellow("WARN");
+		case "error": return colors.red("ERROR");
+	}
+}
+/**
+* Browser (DevTools) sink. Uses `%c` CSS format specifiers so DevTools
+* renders a colored level + namespace prefix, then spreads user args raw so
+* DevTools keeps them as expandable object references (clickable source
+* locations for Error, drill-in for plain objects).
+*
+* For JSON format we still emit a single string — consumers that explicitly
+* asked for JSON want machine-readable output, not DevTools theatrics.
+*/
+function createBrowserConsoleSink(format = "console") {
+	if (format === "json") return (event) => routeSingle(event, formatJSONEvent(event));
+	return (event) => {
+		if (event.kind === "span") {
+			const spanTemplate = `%c%s %cSPAN %c%s %c(%sms)`;
+			const args = userArgsOf(event);
+			const spanPropsString = args.length > 0 ? ` ${safeStringify(Object.assign({}, ...args.filter(isPlainRecord)))}` : "";
+			const { durationLabel } = { durationLabel: String(event.duration) };
+			invokeForLevel("info", spanTemplate + (spanPropsString ? "%s" : ""), cssDim(), timeStr(event.time), cssSpan(), cssNamespace(), event.namespace, cssDim(), durationLabel, ...spanPropsString ? [cssDim(), spanPropsString] : []);
+			return;
+		}
+		const template = `%c%s %c%s %c%s`;
+		const args = userArgsOf(event);
+		invokeForLevel(event.level, template, cssDim(), timeStr(event.time), cssLevel(event.level), levelLabel(event.level), cssNamespace(), event.namespace, event.message, ...args);
+	};
+}
+function isPlainRecord(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function cssDim() {
+	return "color: #888";
+}
+function cssNamespace() {
+	return "color: #0aa; font-weight: bold";
+}
+function cssSpan() {
+	return "color: #a0a; font-weight: bold";
+}
+function cssLevel(level) {
+	switch (level) {
+		case "trace":
+		case "debug": return "color: #888; font-weight: bold";
+		case "info": return "color: #36f; font-weight: bold";
+		case "warn": return "color: #b80; font-weight: bold";
+		case "error": return "color: #c33; font-weight: bold";
+	}
+}
+/**
+* Dispatch to the right console method for the event's level.
+* We intentionally use arrow-style invocation rather than
+* `Function.prototype.bind.call(console.info, console, ...)` so that:
+*   1. Tests can `vi.spyOn(console, 'info')` AFTER the sink is created.
+*   2. DevTools attribute the log line to the caller's source location
+*      (arrows don't appear in the stack between the call and `console.*`).
+*/
+function invokeForLevel(level, ...args) {
+	switch (level) {
+		case "trace":
+		case "debug":
+			console.debug(...args);
+			return;
+		case "info":
+			console.info(...args);
+			return;
+		case "warn":
+			console.warn(...args);
+			return;
+		case "error":
+			console.error(...args);
+			return;
+	}
+}
+/**
+* Route an already-formatted single string to the correct console level.
+* Used for JSON format and for span events where we preserve the pre-formatted
+* shape.
+*/
+function routeSingle(event, text) {
+	if (event.kind === "span") {
+		console.info(text);
+		return;
+	}
+	switch (event.level) {
+		case "trace":
+		case "debug":
+			console.debug(text);
+			return;
+		case "info":
+			console.info(text);
+			return;
+		case "warn":
+			console.warn(text);
+			return;
+		case "error":
+			console.error(text);
+			return;
+	}
+}
+/**
+* Pick the right sink for the current runtime. Browsers get `%c` CSS, Node
+* gets ANSI. Both emit multi-arg spreads so the platform can render objects
+* as expandable references.
+*/
+function createConsoleSink$1(format = "console") {
+	return isBrowserRuntime() ? createBrowserConsoleSink(format) : createTerminalConsoleSink(format);
+}
+//#endregion
 //#region src/pipeline.ts
 const LOG_LEVEL_PRIORITY = {
 	trace: 0,
@@ -324,38 +536,12 @@ function parseNsFilter(ns) {
 	};
 }
 /**
-* 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.
+* Console sink used inside the pipeline builder. Delegates to the structured
+* console sink (browser %c or terminal multi-arg) so the pipeline preserves
+* expandable user args end-to-end.
 */
-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);
+	return createConsoleSink$1(format);
 }
 function createFileSink(path, format) {
 	const writer = createFileWriter(path);
@@ -375,6 +561,19 @@ function createWritableSink(writable, format) {
 	}
 	return (event) => writable.write(event);
 }
+/** Consecutive failures before a throwing output sink is disabled. */
+const OUTPUT_MAX_STRIKES = 3;
+/**
+* Report a dispatch-guard failure WITHOUT going through any pipeline —
+* the error channel for the logger itself must not recurse into the logger.
+* Routes through writeStderr (the `_process` guard) for browser safety.
+*/
+function reportGuard(what, err) {
+	const detail = err instanceof Error ? err.stack ?? err.message : String(err);
+	try {
+		writeStderr(`loggily: ${what}: ${detail}`);
+	} catch {}
+}
 const VALID_CONFIG_KEYS = new Set([
 	"level",
 	"ns",
@@ -478,23 +677,59 @@ function buildPipeline(elements, parentConfig) {
 		}
 		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 stageReported = [];
+	const branchReported = [];
 	const dispatch = (event) => {
 		if (event.kind === "span" && !spansEnabled) return;
 		let e = event;
-		for (const stage of stages) {
-			const result = stage(e);
+		for (let i = 0; i < stages.length; i++) {
+			let result;
+			try {
+				result = stages[i](e);
+			} catch (err) {
+				if (!stageReported[i]) {
+					stageReported[i] = true;
+					reportGuard(`stage #${i} threw — dropping event, fail-closed (reported once)`, err);
+				}
+				return;
+			}
 			if (result === null) return;
 			if (result !== void 0) e = result;
 		}
 		for (const output of outputs) {
+			if (output.disabled) continue;
 			if (e.kind === "log" && LOG_LEVEL_PRIORITY[e.level] < output.levelPriority) continue;
 			if (output.nsFilter && !output.nsFilter(e.namespace)) continue;
-			output.write(e);
+			try {
+				output.write(e);
+				if (output.failures) output.failures = 0;
+			} catch (err) {
+				output.failures = (output.failures ?? 0) + 1;
+				if (output.failures === 1) reportGuard("output write threw — event lost for this sink", err);
+				if (output.failures >= OUTPUT_MAX_STRIKES) {
+					output.disabled = true;
+					reportGuard(`output disabled after ${output.failures} consecutive failures`, err);
+				}
+			}
 		}
-		for (const branch of branches) branch.dispatch(e);
+		for (let i = 0; i < branches.length; i++) try {
+			branches[i].dispatch(e);
+		} catch (err) {
+			if (!branchReported[i]) {
+				branchReported[i] = true;
+				reportGuard(`branch #${i} dispatch threw (reported once)`, err);
+			}
+		}
+	};
+	const spanEnabledForNamespace = (namespace) => {
+		if (!spansEnabled) return false;
+		if (outputs.some((output) => !output.nsFilter || output.nsFilter(namespace))) return true;
+		if (branches.some((branch) => branch.spanEnabled(namespace))) return true;
+		return stages.length > 0;
 	};
 	return {
 		dispatch,
+		spanEnabled: spanEnabledForNamespace,
 		level: config.level,
 		dispose: () => {
 			for (const d of disposables) d();
@@ -573,6 +808,12 @@ function readEnvTrace() {
 * ])
 * log.info?.('server started', { port: 3000 })
 */
+const SPAN_ENABLED = Symbol("loggily.spanEnabled");
+function spanIsEnabled(logger, namespace) {
+	if (collectSpans) return true;
+	const checker = logger[SPAN_ENABLED];
+	return checker ? checker(namespace) : true;
+}
 function resetIds() {
 	resetIdCounters();
 }
@@ -638,6 +879,7 @@ function createLoggerImpl(name, props, pipeline) {
 	const emitLog = (level, msgOrError, dataOrMsg, extraData) => {
 		let message;
 		let data;
+		const userArgs = [];
 		if (msgOrError instanceof Error) {
 			const err = msgOrError;
 			const contextTags = _getContextTags?.() ?? {};
@@ -665,6 +907,8 @@ function createLoggerImpl(name, props, pipeline) {
 					error_cause: err.cause !== void 0 ? serializeCause(err.cause) : void 0
 				};
 			}
+			userArgs.push(err);
+			if (data && Object.keys(data).length > 0) userArgs.push(data);
 		} else {
 			message = resolveMessage(msgOrError);
 			const contextTags = _getContextTags?.();
@@ -676,6 +920,7 @@ function createLoggerImpl(name, props, pipeline) {
 				...props,
 				...dataOrMsg
 			} : void 0;
+			if (data && Object.keys(data).length > 0) userArgs.push(data);
 		}
 		const event = {
 			kind: "log",
@@ -683,7 +928,8 @@ function createLoggerImpl(name, props, pipeline) {
 			namespace: name,
 			level,
 			message,
-			props: data
+			props: data,
+			userArgs
 		};
 		pipeline.dispatch(event);
 	};
@@ -693,6 +939,9 @@ function createLoggerImpl(name, props, pipeline) {
 		get level() {
 			return pipeline.level;
 		},
+		[SPAN_ENABLED](namespace) {
+			return pipeline.spanEnabled(namespace);
+		},
 		dispatch(event) {
 			pipeline.dispatch(event);
 		},
@@ -704,6 +953,7 @@ function createLoggerImpl(name, props, pipeline) {
 		info: (msg, data) => emitLog("info", msg, data),
 		warn: (msg, data) => emitLog("warn", msg, data),
 		error: (msgOrError, dataOrMsg, extraData) => emitLog("error", msgOrError, dataOrMsg, extraData),
+		/** @deprecated Use .child() instead */
 		logger(namespace, childProps) {
 			return this.child(namespace ?? "", childProps);
 		},
@@ -757,8 +1007,9 @@ function augmentWithSpans(logger, parentSpanId, traceId, traceSampled) {
 		traceId,
 		traceSampled
 	};
+	const spanMethod = spanIsEnabled(logger, logger.name) ? createSpanMethod(logger, spanState) : void 0;
 	return new Proxy(logger, { get(target, prop) {
-		if (prop === "span") return createSpanMethod(target, spanState);
+		if (prop === "span") return spanMethod;
 		if (prop === "child") return function child(namespaceOrContext, childProps) {
 			return augmentWithSpans(target.child(namespaceOrContext, childProps), spanState.parentSpanId, spanState.traceId, spanState.traceSampled);
 		};
@@ -796,7 +1047,8 @@ function createSpanMethod(logger, spanState) {
 			startTime: Date.now(),
 			endTime: null,
 			duration: null,
-			attrs: {}
+			attrs: {},
+			laps: []
 		};
 		const spanAugmented = augmentWithSpans(logger.child(namespace ?? "", resolvedChildProps), newSpanId, finalTraceId, sampled);
 		_enterContext?.(newSpanId, finalTraceId, resolvedParentId);
@@ -814,6 +1066,7 @@ function createSpanMethod(logger, spanState) {
 			}), { ...newSpanData.attrs }));
 			_exitContext?.(newSpanId);
 			if (sampled) {
+				const lapsProp = newSpanData.laps.length > 0 ? Object.fromEntries(newSpanData.laps.map((l) => [l.name, l.deltaMs])) : void 0;
 				const spanEvent = {
 					kind: "span",
 					time: newSpanData.endTime,
@@ -822,7 +1075,8 @@ function createSpanMethod(logger, spanState) {
 					duration: newSpanData.duration,
 					props: {
 						...mergedProps,
-						...newSpanData.attrs
+						...newSpanData.attrs,
+						...lapsProp ? { laps: lapsProp } : {}
 					},
 					spanId: newSpanData.id,
 					traceId: newSpanData.traceId,
@@ -831,6 +1085,16 @@ function createSpanMethod(logger, spanState) {
 				logger.dispatch(spanEvent);
 			}
 		};
+		const lapImpl = (name) => {
+			const elapsedMs = Date.now() - newSpanData.startTime;
+			const lastLap = newSpanData.laps[newSpanData.laps.length - 1];
+			const deltaMs = lastLap ? elapsedMs - lastLap.elapsedMs : elapsedMs;
+			newSpanData.laps.push({
+				name,
+				elapsedMs,
+				deltaMs
+			});
+		};
 		const spanDataProxy = createSpanDataProxy(() => ({
 			id: newSpanData.id,
 			traceId: newSpanData.traceId,
@@ -847,6 +1111,7 @@ function createSpanMethod(logger, spanState) {
 				if (prop === "end") return () => {
 					if (newSpanData.endTime === null) currentDispose();
 				};
+				if (prop === "lap") return lapImpl;
 				if (prop === "name") return childName;
 				if (prop === "props") return Object.freeze({ ...mergedProps });
 				return target[prop];
@@ -938,6 +1203,15 @@ function withEnvDefaults() {
 */
 function applyNamespaceGating(logger) {
 	return new Proxy(logger, { get(target, prop) {
+		if (prop === SPAN_ENABLED) return (namespace) => {
+			if (collectSpans) return true;
+			const trace = currentTrace();
+			if (!trace.enabled) return false;
+			if (trace.filter && !trace.filter(namespace)) return false;
+			const ns = currentNs();
+			if (ns && !ns(namespace)) return false;
+			return true;
+		};
 		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;
@@ -966,14 +1240,23 @@ function createEnvPipeline() {
 		}
 		const ns = currentNs();
 		if (ns && !ns(event.namespace)) return;
-		const text = (currentFormat() === "json" ? formatJSONEvent : formatConsoleEvent)(event);
+		const format = currentFormat();
+		const text = (format === "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);
+		for (const w of _writers) w(text, lvl, event.namespace, event);
+		if (!_suppressConsole) createConsoleSink$1(format)(event);
 		fileSink?.(event);
 	};
 	return {
 		dispatch,
+		spanEnabled(namespace) {
+			const trace = currentTrace();
+			if (!trace.enabled) return false;
+			if (trace.filter && !trace.filter(namespace)) return false;
+			const ns = currentNs();
+			if (ns && !ns(namespace)) return false;
+			return true;
+		},
 		get level() {
 			return currentLevel();
 		},
@@ -1048,7 +1331,21 @@ function setOutputMode(_mode) {
 function getOutputMode() {
 	return "console";
 }
-function addWriter(writer) {
+function addWriter(arg1, arg2) {
+	if (typeof arg1 === "function") return _addRawWriter(arg1);
+	if (!arg2) throw new Error("addWriter: writer fn required when first argument is a config object");
+	const config = arg1;
+	const matches = config.ns ? parseNsFilter(config.ns) : null;
+	const minPriority = config.level ? LOG_LEVEL_PRIORITY[config.level] : null;
+	return _addRawWriter((formatted, level, namespace, event) => {
+		if (matches && !matches(namespace)) return;
+		if (minPriority !== null) {
+			if ((LOG_LEVEL_PRIORITY[level] ?? LOG_LEVEL_PRIORITY.info) < minPriority) return;
+		}
+		arg2(formatted, level, namespace, event);
+	});
+}
+function _addRawWriter(writer) {
 	_writers.push(writer);
 	return () => {
 		const i = _writers.indexOf(writer);
@@ -1071,4 +1368,4 @@ function writeSpan(namespace, duration, attrs) {
 //#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
+//# sourceMappingURL=core-DKwMMOZw.mjs.map