@mks2508/better-logger 0.18.2-alpha.2 → 0.18.3

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  * cross-runtime styling/utility helpers. Side-effect free at import.
  */
 import { Logger } from './Logger.js';
-import type { Verbosity, ThemeVariant, BannerType, StyleOptions, ILogHandler } from './types/index.js';
+import type { Verbosity, ThemeVariant, BannerType, StyleOptions, ILogHandler, Span, SpanAttributes } from './types/index.js';
 /**
  * Main `Logger` class — orchestrator for styling, transports, hooks,
  * serializers, MDC, and CLI primitives. Construct directly or use the
@@ -32,6 +32,10 @@ export declare const group: (label: string, collapsed?: boolean) => void;
 export declare const groupEnd: () => void;
 export declare const time: (label: string) => void;
 export declare const timeEnd: (label: string) => number;
+export declare const event: (name: string, attributes?: SpanAttributes) => void;
+export declare const startSpan: (name: string, attributes?: SpanAttributes) => Span;
+export declare function span<T>(name: string, fn: (s: Span) => T | Promise<T>): Promise<T>;
+export declare function span<T>(name: string, attributes: SpanAttributes, fn: (s: Span) => T | Promise<T>): Promise<T>;
 export declare const setGlobalPrefix: (prefix: string) => void;
 export declare const scope: (name: string) => import("./ScopedLogger.js").ScopedLogger;
 export declare const component: (name: string) => import("./ScopedLogger.js").ComponentLogger;

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -1,10 +1,10 @@
+import { n as resolveAsyncLocalStorage, t as createLogContext } from "./chunks/LogContext-Dyzs61XG.js";
 import { t as LOG_LEVELS } from "./chunks/core-Blfi2klP.js";
-import { o as LOG_LEVEL_TO_SEVERITY_NUMBER, s as LOG_LEVEL_TO_SEVERITY_TEXT, t as TransportManager } from "./chunks/transports-BGfwwakw.js";
+import { c as LOG_LEVEL_TO_SEVERITY_TEXT, s as LOG_LEVEL_TO_SEVERITY_NUMBER, t as TransportManager } from "./chunks/transports-DvaLAeGJ.js";
 import { _ as DEFAULT_CONFIG, a as safeSerialize, b as parseStackTrace, c as ansiBackground, d as ansiDim, f as ansiStyle, g as CLI_LEVEL_MAP, h as formatSuccessANSI, i as getConsoleMethod, l as ansiBold, m as formatLogLevelANSI, o as createStyledOutput, p as ansiUnderline, r as formatTablePlain, s as setupThemeChangeListener, t as createLogEntry, u as ansiColor, y as formatTimestamp } from "./chunks/utils-tKfBAWUM.js";
 import { a as THEME_BANNERS, c as StyleBuilder, i as BANNER_VARIANTS, l as StylePresets, n as getSmartPreset, o as displayInitBanner, r as hasPreset, s as THEME_PRESETS, t as getAvailablePresets } from "./chunks/styling-CRw3KQW4.js";
 import { a as getTerminalWidth, c as isRunningInTerminal, i as getTerminalHeight, l as supportsANSI, n as getEnvironment, r as getEnvironmentInfo, t as getColorCapability } from "./chunks/environment-detector-7NvnYUfr.js";
 import { a as renderDivider, c as formatBadge, i as renderBox, n as SpinnerManager, o as renderHeader, r as renderTable, s as renderStep, t as NoopSpinner } from "./chunks/spinner-BtkwpzYv.js";
-import { t as createLogContext } from "./chunks/LogContext-DjlITOzZ.js";
 import { t as createHookBridge } from "./chunks/HookBridge-CI2PH79S.js";
 import { t as createSerializerBridge } from "./chunks/SerializerBridge-Ba43Mk7j.js";
 import { t as ServerFallback } from "./chunks/server-fallback-jj0T6XaK.js";
@@ -289,6 +289,34 @@ var ScopedLogger = class {
 		this.parent.logWithBindings(this.getBindings(), "trace", ...args);
 	}
 	/**
+	* Emite un point-span con el scope de este logger como
+	* `SpanRecord.scope`. Ver {@link Logger.event}.
+	*
+	* @param {string} name - Nombre del evento.
+	* @param {SpanAttributes} [attributes] - Attributes del span.
+	*
+	* @example
+	* logger.scope('BUILD').event('step.done', { step: 'compile' });
+	*/
+	event(name, attributes) {
+		this.parent._emitSpanEvent(name, attributes, this.getScopePrefix());
+	}
+	span(name, fnOrAttributes, maybeFn) {
+		const { attributes, fn } = resolveSpanArgs(fnOrAttributes, maybeFn);
+		return this.parent._runSpan(name, attributes, this.getScopePrefix(), fn);
+	}
+	/**
+	* Inicia un span externally-ended etiquetado con el scope de este
+	* logger. Ver {@link Logger.startSpan}.
+	*
+	* @param {string} name - Nombre de la operación.
+	* @param {SpanAttributes} [attributes] - Attributes iniciales.
+	* @returns {Span} Handle con `set`/`end`/`fail`.
+	*/
+	startSpan(name, attributes) {
+		return this.parent._startSpan(name, attributes, this.getScopePrefix());
+	}
+	/**
 	* Delegación a {@link Logger.step}: dibuja una barra de progreso discreta
 	* `current/total` para este scope.
 	*
@@ -1533,6 +1561,164 @@ function createTransportBridge() {
 	};
 }
 //#endregion
+//#region src/transports/SpanRuntime.ts
+/** ALS singleton del módulo — compartido por todas las instancias de Logger.
+*
+* Resolución por capas (global → `process.getBuiltinModule` → `require`,
+* undefined en browser) delegada al helper compartido
+* {@link resolveAsyncLocalStorage} — ver su doc para el detalle de capas.
+* `context/LogContext.ts` usa el mismo helper para su ALS de MDC. */
+const activeSpanStore = resolveAsyncLocalStorage();
+/**
+* Span activo en el call stack corriente (dentro de `span(fn)`), si lo hay.
+* Lo consumen la correlación log→span (`TransportRecord.traceId/spanId`) y la
+* resolución de `parentSpanId` en spans hijos.
+*/
+function getActiveSpan() {
+	return activeSpanStore?.getStore();
+}
+/**
+* Ejecuta `fn` con `record` como span activo. Sin ALS disponible (browser),
+* ejecuta `fn` directamente — sin correlación pero funcional.
+*/
+function runWithActiveSpan(record, fn) {
+	return activeSpanStore ? activeSpanStore.run(record, fn) : fn();
+}
+/** Nanosegundos Unix actuales como string decimal (formato OTLP). */
+function nowUnixNano() {
+	return String(BigInt(Date.now()) * 1000000n);
+}
+/**
+* Hex aleatorio de `bytes` bytes. Usa `crypto.getRandomValues`; sin
+* `crypto` (runtimes exóticos) degrada a `Math.random` — suficiente para ids
+* de correlación, no para secrets.
+*/
+function randomHex(bytes) {
+	const cryptoObj = globalThis.crypto;
+	if (cryptoObj?.getRandomValues) {
+		const buf = new Uint8Array(bytes);
+		cryptoObj.getRandomValues(buf);
+		let out = "";
+		for (const b of buf) out += b.toString(16).padStart(2, "0");
+		return out;
+	}
+	let out = "";
+	for (let i = 0; i < bytes * 2; i++) out += Math.floor(Math.random() * 16).toString(16);
+	return out;
+}
+/** Trace id W3C: 16 bytes → 32 chars hex. */
+function generateTraceId() {
+	return randomHex(16);
+}
+/** Span id W3C: 8 bytes → 16 chars hex. */
+function generateSpanId() {
+	return randomHex(8);
+}
+/**
+* Registry de spans abiertos (leak-safety). Cubre tanto los de `startSpan()`
+* (externally-ended, el caso del handoff) como los de `span(fn)` en curso:
+* si un flush llega mid-flight, es mejor exportar el span incompleto que
+* tirarlo. El doble-`end()` es no-op, así que el cierre natural posterior no
+* duplica el export.
+*/
+const openSpans = /* @__PURE__ */ new Map();
+/**
+* Crea el record de span y su {@link Span} handle. El handle registra el
+* span en el registry de abiertos; `onEnd` se invoca una única vez, con el
+* record final (duración real o `incomplete: true`), para su export al
+* pipeline de transports.
+*
+* `end()` solo fija `endTimeUnixNano` si no se fijó antes — así los
+* point-spans (`event()`) pueden fijar `end = start` exacto.
+*
+* @param name - Nombre de la operación.
+* @param attributes - Attributes iniciales (copia propia del record).
+* @param scope - Scope del logger emisor.
+* @param onEnd - Callback de export; recibe el record cerrado.
+* @returns El record (para el ALS store) y el handle del span.
+*/
+function createSpan(name, attributes, scope, onEnd) {
+	const parent = getActiveSpan();
+	const record = {
+		kind: "span",
+		traceId: parent?.traceId ?? generateTraceId(),
+		spanId: generateSpanId(),
+		parentSpanId: parent?.spanId,
+		name,
+		spanKind: 1,
+		startTimeUnixNano: nowUnixNano(),
+		endTimeUnixNano: "0",
+		attributes: { ...attributes ?? {} },
+		scope
+	};
+	let ended = false;
+	const finish = () => {
+		if (ended) return;
+		ended = true;
+		openSpans.delete(record);
+		onEnd(record);
+	};
+	openSpans.set(record, {
+		record,
+		end: finish,
+		forceEnd: () => {
+			if (ended) return;
+			record.incomplete = true;
+			if (record.endTimeUnixNano === "0") record.endTimeUnixNano = nowUnixNano();
+			finish();
+		}
+	});
+	const handle = {
+		traceId: record.traceId,
+		spanId: record.spanId,
+		set(key, value) {
+			record.attributes[key] = value;
+			return handle;
+		},
+		end(attributes) {
+			if (attributes) Object.assign(record.attributes, attributes);
+			if (ended) return;
+			if (record.endTimeUnixNano === "0") record.endTimeUnixNano = nowUnixNano();
+			finish();
+		},
+		fail(err) {
+			if (ended) return;
+			record.status = {
+				code: 2,
+				message: err instanceof Error ? err.message : String(err)
+			};
+			this.end();
+		}
+	};
+	return {
+		record,
+		span: handle
+	};
+}
+/**
+* Emite un point-span (`event()`): start = end exactamente, sin registro en
+* abiertos tras el cierre — no hay leak posible. El `parentSpanId` se resuelve
+* contra el span activo si existe, pero NO fija contexto ALS.
+*/
+function emitEventSpan(name, attributes, scope, onEnd) {
+	const { record, span } = createSpan(name, attributes, scope, onEnd);
+	record.endTimeUnixNano = record.startTimeUnixNano;
+	span.end();
+}
+/**
+* Fuerza el cierre de todos los spans abiertos (`incomplete: true`) y los
+* exporta vía el `onEnd` de cada uno. Lo invocan `flushTransports()` /
+* `closeTransports()` / `cleanup()` ANTES del flush real — un span abierto
+* nunca se tira en shutdown.
+*
+* @returns Los records forzados a cerrar (para diagnóstico/tests).
+*/
+function forceCloseOpenSpans() {
+	const snapshot = [...openSpans.values()];
+	for (const entry of snapshot) entry.forceEnd();
+	return snapshot.map((entry) => entry.record);
+}
+//#endregion
 //#region src/playground/TerminalBridge.ts
 /**
 * Crea un {@link TerminalBridge} usando un getter para evitar referencias
@@ -2008,6 +2194,7 @@ var Logger = class Logger {
 			} catch {}
 			this.themeChangeListener = null;
 		}
+		forceCloseOpenSpans();
 		await this.transportBridge.closeTransports();
 		this.handlers.length = 0;
 		this.timers.clear();
@@ -2430,21 +2617,27 @@ var Logger = class Logger {
 		return this.transportBridge.removeTransport(id);
 	}
 	/**
-	* Fuerza el flush de todos los transports
+	* Fuerza el flush de todos los transports. Antes de flushear, cierra los
+	* spans aún abiertos (`incomplete: true`) y los encola para export — un
+	* span abierto nunca se tira en un flush.
 	*
 	* @returns Promise que resuelve cuando todos los buffers están vaciados
 	*
 	*/
 	async flushTransports() {
+		forceCloseOpenSpans();
 		await this.transportBridge.flushTransports();
 	}
 	/**
-	* Cierra todos los transports
+	* Cierra todos los transports. Como en {@link flushTransports}, primero
+	* fuerza el cierre de los spans abiertos para que viajen en el flush
+	* final del close.
 	*
 	* @returns Promise que resuelve cuando todos están cerrados
 	*
 	*/
 	async closeTransports() {
+		forceCloseOpenSpans();
 		await this.transportBridge.closeTransports();
 	}
 	/**
@@ -2546,6 +2739,11 @@ var Logger = class Logger {
 			resource: this.logContext._getResource() ? { ...this.logContext._getResource() } : void 0,
 			...extra
 		};
+		const activeSpan = getActiveSpan();
+		if (activeSpan && !record.traceId) {
+			record.traceId = activeSpan.traceId;
+			record.spanId = activeSpan.spanId;
+		}
 		this.transportBridge.writeRecord(record);
 	}
 	/**
@@ -2802,6 +3000,104 @@ var Logger = class Logger {
 		return this.log("critical", ...args);
 	}
 	/**
+	* Emite un **point-span**: un span con `start = end` para completion
+	* signals y eventos puntuales (una operación instantánea, un hito).
+	* No registra contexto activo ni puede leakear — se exporta de inmediato.
+	*
+	* El nombre `event` (y no `trace`) es deliberado: `trace` es un log level
+	* (el -1) y está reservado.
+	*
+	* @param {string} name - Nombre del evento (`job.completed`, `cache.flushed`, ...).
+	* @param {SpanAttributes} [attributes] - Attributes del span.
+	*
+	* @example
+	* logger.event('build.finished', { status: 'ok', durationMs: 4200 });
+	*
+	* @see {@link span} para intervalos con work-block
+	* @see {@link startSpan} para intervalos externally-ended
+	*/
+	event(name, attributes) {
+		emitEventSpan(name, attributes, this._spanScopeName(), (record) => {
+			this.transportBridge.writeRecord(record);
+		});
+	}
+	span(name, fnOrAttributes, maybeFn) {
+		const { attributes, fn } = resolveSpanArgs(fnOrAttributes, maybeFn);
+		return this._runSpan(name, attributes, this._spanScopeName(), fn);
+	}
+	/**
+	* Inicia un span de intervalo **externally-ended**: devuelve el handle y
+	* NO fija contexto ALS (el cierre ocurre fuera del bloque léxico — p.ej.
+	* un `cli.spawn` que se cierra desde un poll o callback externo).
+	*
+	* Si el span no se cierra antes de `flushTransports()` / shutdown, el
+	* flush lo fuerza a cerrar con `incomplete: true` y lo exporta — nunca
+	* se tira.
+	*
+	* @param {string} name - Nombre de la operación.
+	* @param {SpanAttributes} [attributes] - Attributes iniciales.
+	* @returns {Span} Handle con `set`/`end`/`fail` y los ids del span.
+	*
+	* @example
+	* const s = logger.startSpan('spawn.build', { cmd: 'make' });
+	* proc.on('exit', code => {
+	*   if (code === 0) s.end({ exitCode: code });
+	*   else s.fail(new Error(`exit ${code}`));
+	* });
+	*
+	* @see {@link span} para el caso con work-block
+	*/
+	startSpan(name, attributes) {
+		return this._startSpan(name, attributes, this._spanScopeName());
+	}
+	/**
+	* Scope por defecto de los spans emitidos por este logger (el
+	* `globalPrefix`, o `'root'`).
+	* @internal
+	*/
+	_spanScopeName() {
+		return this.config.globalPrefix || "root";
+	}
+	/**
+	* Emite un point-span con scope explícito. Lo consume
+	* {@link ScopedLogger.event}, que pasa su scope compuesto.
+	* @internal
+	*/
+	_emitSpanEvent(name, attributes, scope) {
+		emitEventSpan(name, attributes, scope, (record) => {
+			this.transportBridge.writeRecord(record);
+		});
+	}
+	/**
+	* Crea un span externally-ended con scope explícito. Lo consume
+	* {@link ScopedLogger.startSpan}.
+	* @internal
+	*/
+	_startSpan(name, attributes, scope) {
+		const { span } = createSpan(name, attributes, scope, (record) => {
+			this.transportBridge.writeRecord(record);
+		});
+		return span;
+	}
+	/**
+	* Corre `fn` dentro de un span activo en el ALS con scope explícito.
+	* Lo consume {@link ScopedLogger.span}.
+	* @internal
+	*/
+	async _runSpan(name, attributes, scope, fn) {
+		const { record, span } = createSpan(name, attributes, scope, (r) => {
+			this.transportBridge.writeRecord(r);
+		});
+		try {
+			const result = await runWithActiveSpan(record, () => fn(span));
+			span.end();
+			return result;
+		} catch (error) {
+			span.fail(error);
+			throw error;
+		}
+	}
+	/**
 	* Muestra datos en formato de tabla. Pasa por la pipeline completa
 	* (outputMode-respecting writeOutput + transports + hooks).
 	*
@@ -3266,6 +3562,23 @@ function toAttributeValue(value) {
 		return;
 	}
 }
+/**
+* Resuelve los argumentos del overload `span(name, fn?)` /
+* `span(name, attributes, fn)` a `{ attributes, fn }`.
+*
+* @internal Compartido con `ScopedLogger.span`; no es API pública.
+*/
+function resolveSpanArgs(fnOrAttributes, maybeFn) {
+	if (typeof fnOrAttributes === "function") return {
+		attributes: void 0,
+		fn: fnOrAttributes
+	};
+	if (typeof maybeFn === "function") return {
+		attributes: fnOrAttributes,
+		fn: maybeFn
+	};
+	throw new TypeError("span(name, …): se requiere una función fn");
+}
 //#endregion
 //#region src/index.ts
 /**
@@ -3298,6 +3611,11 @@ const group = (label, collapsed) => getLogger().group(label, collapsed);
 const groupEnd = () => getLogger().groupEnd();
 const time = (label) => getLogger().time(label);
 const timeEnd = (label) => getLogger().timeEnd(label);
+const event = (name, attributes) => getLogger().event(name, attributes);
+const startSpan = (name, attributes) => getLogger().startSpan(name, attributes);
+function span(name, fnOrAttributes, maybeFn) {
+	return getLogger().span(name, fnOrAttributes, maybeFn);
+}
 const setGlobalPrefix = (prefix) => getLogger().setGlobalPrefix(prefix);
 const scope = (name) => getLogger().scope(name);
 const component = (name) => getLogger().component(name);
@@ -3324,6 +3642,6 @@ const removeTransport = (id) => getLogger().removeTransport(id);
 const flushTransports = () => getLogger().flushTransports();
 const closeTransports = () => getLogger().closeTransports();
 //#endregion
-export { APILogger, BANNER_VARIANTS, ComponentLogger, ContextLogger, DEFAULT_CONFIG, Logger, ScopedLogger, StyleBuilder, StylePresets, THEME_BANNERS, THEME_PRESETS, addHandler, addSerializer, addTransport, ansiBackground, ansiBold, ansiColor, ansiDim, ansiStyle, ansiUnderline, api, badge, badges, clearBadges, cli, closeTransports, component, createLogEntry, critical, debug, src_default as default, error, flushTransports, formatLogLevelANSI, formatSuccessANSI, formatTablePlain, formatTimestamp, getColorCapability, getConsoleMethod, getEnvironment, getEnvironmentInfo, getTerminalHeight, getTerminalWidth, group, groupEnd, info, isRunningInTerminal, logAnimated, logWithSVG, off, on, once, parseStackTrace, removeSerializer, removeTransport, safeSerialize, scope, setBannerType, setGlobalPrefix, setTheme, setVerbosity, showBanner, success, supportsANSI, table, time, timeEnd, trace, use, warn };
+export { APILogger, BANNER_VARIANTS, ComponentLogger, ContextLogger, DEFAULT_CONFIG, Logger, ScopedLogger, StyleBuilder, StylePresets, THEME_BANNERS, THEME_PRESETS, addHandler, addSerializer, addTransport, ansiBackground, ansiBold, ansiColor, ansiDim, ansiStyle, ansiUnderline, api, badge, badges, clearBadges, cli, closeTransports, component, createLogEntry, critical, debug, src_default as default, error, event, flushTransports, formatLogLevelANSI, formatSuccessANSI, formatTablePlain, formatTimestamp, getColorCapability, getConsoleMethod, getEnvironment, getEnvironmentInfo, getTerminalHeight, getTerminalWidth, group, groupEnd, info, isRunningInTerminal, logAnimated, logWithSVG, off, on, once, parseStackTrace, removeSerializer, removeTransport, safeSerialize, scope, setBannerType, setGlobalPrefix, setTheme, setVerbosity, showBanner, span, startSpan, success, supportsANSI, table, time, timeEnd, trace, use, warn };
 
 //# sourceMappingURL=index.js.map