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

package/dist/chunks/HookBridge-CI2PH79S.js

@@ -0,0 +1,487 @@
+//#region src/hooks/HookManager.ts
+/**
+* Profundidad máxima de reentrancia permitida para el evento `onError`.
+*
+* Cuando un hook registrado para `onError` lanza una excepción, el manager
+* re-emite el error como un nuevo evento `onError`, lo que podría entrar en
+* un bucle infinito. Este límite corta la cadena tras N niveles de anidamiento
+* y deja caer el entry al console para no acaparar el event loop.
+*
+* @internal Constantante de implementación; no forma parte de la API pública.
+*/
+const MAX_ONERROR_DEPTH = 5;
+/**
+* Genera un identificador corto y único para cada registro de hook/middleware.
+*
+* Combina timestamp con un segmento aleatorio base36. Suficiente para
+* desambiguar registros dentro de un mismo proceso; no es un UUID criptográfico.
+*
+* @internal Helper interno; no es API pública.
+* @returns {string} ID tipo `<epoch>-<random9>`.
+*/
+function generateId() {
+	return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+/**
+* Implementación por defecto de {@link IHookManager} que orquesta el ciclo de
+* vida de los hooks del logger: `beforeLog`, `afterLog` y `onError`.
+*
+* Permite:
+* - Registrar callbacks por evento con **prioridad** (mayor número = se
+*   ejecuta primero; las registraciones se ordenan descendentemente).
+* - Encadenar middlewares sobre el entry previo al dispatch.
+* - Propagar mutaciones: cada hook puede retornar un partial de
+*   {@link HookLogEntry} que se mergea al entry actual antes del siguiente hook.
+* - Acotar la recursión de `onError` con un guard de profundidad
+*   ({@link MAX_ONERROR_DEPTH}) para que un hook que lanza no loopée para
+*   siempre.
+*
+* El flujo típico lo orquesta el logger vía {@link process} (emite `beforeLog`
+* + ejecuta middlewares) y {@link afterProcess} (emite `afterLog`).
+*
+* @example
+* ```ts
+* const hooks = new HookManager();
+*
+* // Mayor prioridad => corre primero
+* hooks.on('beforeLog', (entry) => {
+*   return { ...entry, attributes: { ...entry.attributes, traced: true } };
+* }, 90);
+*
+* hooks.on('afterLog', (entry) => {
+*   metrics.increment('log_emitted', { level: entry.level });
+* });
+*
+* hooks.on('onError', (entry) => {
+*   telemetry.capture(entry.error);
+* });
+* ```
+*
+* @example
+* ```ts
+* // Middleware que añade timestamp si falta y delega al siguiente
+* hooks.use(async (entry, next) => {
+*   if (!entry.time) entry.time = Date.now();
+*   await next();
+* });
+* ```
+*
+* @see {@link IHookManager}
+* @see {@link HookEvent}
+*/
+var HookManager = class {
+	hooks = /* @__PURE__ */ new Map();
+	middlewares = [];
+	/**
+	* Lleva el conteo de la profundidad de recursión actual por cada evento de
+	* hook, para que las cadenas de `onError` que lanzan excepciones no puedan
+	* loopéar para siempre. Se resetea cuando el `emit` externo retorna.
+	*/
+	_onErrorDepth = /* @__PURE__ */ new Map();
+	constructor() {
+		this.hooks.set("beforeLog", []);
+		this.hooks.set("afterLog", []);
+		this.hooks.set("onError", []);
+	}
+	/**
+	* Registra un callback persistente para un evento. Se ejecuta en cada
+	* emisión hasta que se cancele con la función devuelta o con {@link off}.
+	*
+	* Los hooks se ordenan por `priority` **descendente**: mayor número =
+	* se ejecuta primero. Misma prioridad respeta el orden de registro.
+	*
+	* @param event - Uno de `'beforeLog' | 'afterLog' | 'onError'`.
+	* @param callback - Función asíncrona que recibe el {@link HookLogEntry}
+	*   actual y puede retornar un partial para mutar el entry que verán los
+	*   hooks siguientes.
+	* @param priority - Peso de ordenamiento. Default `50`. Mayor = primero.
+	* @returns {() => void} Función de cancelación; llamarla desregistra el hook.
+	*
+	* @example
+	* ```ts
+	* const off = hooks.on('beforeLog', async (entry) => {
+	*   return { attributes: { ...entry.attributes, requestId: getReqId() } };
+	* }, 80);
+	*
+	* // ...en shutdown:
+	* off();
+	* ```
+	*
+	* @see {@link once} para hooks de un solo disparo.
+	* @see {@link off} para desregistro por referencia de callback.
+	*/
+	on(event, callback, priority = 50) {
+		const registration = {
+			id: generateId(),
+			event,
+			callback,
+			priority,
+			once: false
+		};
+		const hooks = this.hooks.get(event);
+		hooks.push(registration);
+		hooks.sort((a, b) => b.priority - a.priority);
+		return () => this.removeHook(event, registration.id);
+	}
+	/**
+	* Igual que {@link on}, pero el hook se auto-desregistra después del primer
+	* disparo exitoso. Útil para setup one-shot (warm-up de caché, captura del
+	* primer log, ...).
+	*
+	* Si el callback lanza, el hook NO se elimina (la excepción se deriva a
+	* `onError`); la limpieza solo ocurre cuando el callback retorna sin Throw.
+	*
+	* @param event - Evento a escuchar.
+	* @param callback - Handler que se ejecutará una sola vez.
+	* @param priority - Peso de ordenamiento (mayor = primero). Default `50`.
+	* @returns {() => void} Cancelación manual por si se quiere retirar antes
+	*   del primer disparo.
+	*
+	* @example
+	* ```ts
+	* hooks.once('afterLog', async (entry) => {
+	*   console.log('Primer log emitido:', entry.msg);
+	* });
+	* ```
+	*
+	* @see {@link on}
+	*/
+	once(event, callback, priority = 50) {
+		const registration = {
+			id: generateId(),
+			event,
+			callback,
+			priority,
+			once: true
+		};
+		const hooks = this.hooks.get(event);
+		hooks.push(registration);
+		hooks.sort((a, b) => b.priority - a.priority);
+		return () => this.removeHook(event, registration.id);
+	}
+	/**
+	* Desregistra un hook por referencia de callback. Solo elimina la primera
+	* coincidencia encontrada para el evento.
+	*
+	* Para hooks registrados con {@link on} o {@link once} es preferible usar
+	* la función de cancelación devuelta (que usa el id interno y es O(n) más
+	* directa). `off` es útil cuando se perdió la referencia al cancelador o
+	* cuando se integra con APIs que piden un método `removeListener(cb)`.
+	*
+	* @param event - Evento del que se quiere desregistrar.
+	* @param callback - Misma referencia de función pasada a {@link on}/{@link once}.
+	* @returns {boolean} `true` si se eliminó un hook, `false` si no había match.
+	*
+	* @example
+	* ```ts
+	* const handler = async (entry) => { /* ... *\/ };
+	* hooks.on('afterLog', handler);
+	* hooks.off('afterLog', handler); // true
+	* ```
+	*
+	* @see {@link on}
+	*/
+	off(event, callback) {
+		const hooks = this.hooks.get(event);
+		if (!hooks) return false;
+		const index = hooks.findIndex((h) => h.callback === callback);
+		if (index >= 0) {
+			hooks.splice(index, 1);
+			return true;
+		}
+		return false;
+	}
+	removeHook(event, id) {
+		const hooks = this.hooks.get(event);
+		if (hooks) {
+			const index = hooks.findIndex((h) => h.id === id);
+			if (index >= 0) hooks.splice(index, 1);
+		}
+	}
+	/**
+	* Registra un middleware que se encadena sobre el {@link HookLogEntry}
+	* **antes** de que se emita el log al resto del pipeline. Los middlewares
+	* corren después del evento `beforeLog` y se ejecutan en cascada vía `next()`.
+	*
+	* Cada middleware recibe `(entry, next)` y debe llamar a `next()` para
+	* ceder el control al siguiente. Si NO llama a `next()`, corta la cadena
+	* (patrón short-circuit).
+	*
+	* Ordenamiento: `priority` descendente (mayor = primero), igual que los
+	* hooks. La secuencia respetada es la del sort, no la del orden de
+	* llamada a `use`.
+	*
+	* @param middleware - Función `(entry, next) => Promise<void>`.
+	* @param priority - Peso de ordenamiento. Default `50`.
+	* @returns {() => void} Función de cancelación para retirar el middleware.
+	*
+	* @example
+	* ```ts
+	* // PII redaction: enmascara passwords antes de loguear
+	* hooks.use(async (entry, next) => {
+	*   if (entry.attributes?.password) {
+	*     entry.attributes.password = '***';
+	*   }
+	*   await next();
+	* }, 90);
+	*
+	* // Short-circuit: si es level=debug y env=prod, no baja
+	* const stop = hooks.use(async (entry, next) => {
+	*   if (entry.level === 'debug' && ENV === 'production') return;
+	*   await next();
+	* }, 100);
+	* ```
+	*
+	* @see {@link process} para el orquestador que ejecuta la cadena.
+	*/
+	use(middleware, priority = 50) {
+		const registration = {
+			id: generateId(),
+			fn: middleware,
+			priority
+		};
+		this.middlewares.push(registration);
+		this.middlewares.sort((a, b) => b.priority - a.priority);
+		return () => {
+			const index = this.middlewares.findIndex((m) => m.id === registration.id);
+			if (index >= 0) this.middlewares.splice(index, 1);
+		};
+	}
+	/**
+	* Emite un evento a todos sus hooks registrados, en orden de prioridad, y
+	* retorna el entry resultante tras aplicar todos los mutations.
+	*
+	* Cada hook puede retornar un partial de {@link HookLogEntry}; ese partial
+	* se mergea sobre el entry actual antes de invocar al siguiente hook, así
+	* los hooks se encadenan como una pipeline de transformaciones.
+	*
+	* Manejo de errores:
+	* - Si un hook de `beforeLog`/`afterLog` lanza, la excepción se captura y
+	*   se re-emite como evento `onError` con el campo `error` poblado.
+	* - Si un hook de `onError` lanza, **NO** se re-emite (rompería el ciclo);
+	*   se loguea a `console.error` y se traga.
+	* - Guard de reentrancia: si `onError` se re-entra más de
+	*   {@link MAX_ONERROR_DEPTH} veces, se corta y se loguea el entry al
+	*   console. Previene loops infinitos por errores en cascada.
+	*
+	* Los hooks marcados como `once` se eliminan tras un disparo exitoso.
+	*
+	* @param event - Evento a emitir.
+	* @param entry - Entry inicial; no se muta in-place (se clona por nivel).
+	* @returns {Promise<HookLogEntry>} Entry transformado tras todos los hooks.
+	*
+	* @example
+	* ```ts
+	* const enriched = await hooks.emit('beforeLog', rawEntry);
+	* // enriched.attributes puede traer merges de varios hooks
+	* ```
+	*
+	* @see {@link on}
+	* @see {@link once}
+	* @see {@link MAX_ONERROR_DEPTH}
+	*/
+	async emit(event, entry) {
+		const depth = this._onErrorDepth.get(entry.hookEvent ?? event) ?? 0;
+		if (event === "onError" && depth >= MAX_ONERROR_DEPTH) {
+			console.error("HookManager: onError recursion limit reached, dropping entry:", entry);
+			return entry;
+		}
+		this._onErrorDepth.set(event, depth + 1);
+		try {
+			const hooks = this.hooks.get(event) || [];
+			let currentEntry = { ...entry };
+			const toRemove = [];
+			for (const hook of hooks) try {
+				const result = await hook.callback(currentEntry);
+				if (result) currentEntry = {
+					...currentEntry,
+					...result
+				};
+				if (hook.once) toRemove.push(hook.id);
+			} catch (error) {
+				if (event !== "onError") await this.emit("onError", {
+					...currentEntry,
+					error: error instanceof Error ? error : new Error(String(error)),
+					hookEvent: event
+				});
+				else console.error("HookManager: onError hook threw, swallowed to break recursion:", error);
+			}
+			toRemove.forEach((id) => this.removeHook(event, id));
+			return currentEntry;
+		} finally {
+			this._onErrorDepth.set(event, depth);
+		}
+	}
+	/**
+	* Orquesta el pipeline pre-emit de un log. Orden de ejecución:
+	*
+	* 1. Emite `beforeLog` (todos sus hooks corren en orden de prioridad y
+	*    pueden mutar el entry vía return partial).
+	* 2. Si hay middlewares registrados ({@link use}), los ejecuta en cascada
+	*    sobre el entry ya enriquecido por los hooks de `beforeLog`.
+	*
+	* Es el punto de entrada que el logger invoca **antes** de despachar el
+	* record a los transports. El entry devuelto es el que finalmente se loguea.
+	*
+	* No emite `afterLog`; para eso usar {@link afterProcess} una vez que el
+	* dispatch al transport haya terminado.
+	*
+	* @param entry - Entry crudo entrante al pipeline.
+	* @returns {Promise<HookLogEntry>} Entry final listo para mandar a transports.
+	*
+	* @example
+	* ```ts
+	* const processed = await hooks.process(rawEntry);
+	* await transport.write(processed);
+	* await hooks.afterProcess(processed);
+	* ```
+	*
+	* @see {@link afterProcess}
+	* @see {@link use}
+	*/
+	async process(entry) {
+		let currentEntry = { ...entry };
+		currentEntry = await this.emit("beforeLog", currentEntry);
+		if (this.middlewares.length > 0) {
+			let index = 0;
+			const executeNext = async () => {
+				if (index < this.middlewares.length) {
+					const middleware = this.middlewares[index++];
+					if (middleware) await middleware.fn(currentEntry, executeNext);
+				}
+			};
+			await executeNext();
+		}
+		return currentEntry;
+	}
+	/**
+	* Emite el evento `afterLog` con el entry ya procesado y dispatcheado a
+	* los transports. Pensado para side-effects post-log: métricas, audit
+	* trail, flush de buffers externos, etc.
+	*
+	* Los hooks de `afterLog` pueden retornar un partial pero el entry ya se
+	* ha publicado, así que la mutación no tiene efecto sobre el log emitido;
+	* solo queda disponible en el return de {@link emit}, que aquí se descarta.
+	*
+	* @param entry - Entry final (mismo objeto devuelto por {@link process}).
+	* @returns {Promise<void>} Resuelve cuando todos los hooks terminaron.
+	*
+	* @example
+	* ```ts
+	* hooks.on('afterLog', async (entry) => {
+	*   metrics.increment('logs_total', { level: entry.level });
+	* });
+	*
+	* const processed = await hooks.process(rawEntry);
+	* await transport.write(processed);
+	* await hooks.afterProcess(processed); // dispara métricas
+	* ```
+	*
+	* @see {@link process}
+	*/
+	async afterProcess(entry) {
+		await this.emit("afterLog", entry);
+	}
+	/**
+	* Vacía todos los hooks y middlewares registrados. Útil para resetear el
+	* estado entre tests o en hot-reload.
+	*
+	* Afecta a los tres eventos (`beforeLog`, `afterLog`, `onError`) y a la
+	* pila de middlewares. Las funciones de cancelación devueltas por
+	* {@link on}/{@link once}/{@link use} se vuelven no-ops pero pueden
+	* llamarse sin error.
+	*
+	* @example
+	* ```ts
+	* afterEach(() => hooks.clear());
+	* ```
+	*/
+	clear() {
+		this.hooks.forEach((hooks) => hooks.length = 0);
+		this.middlewares.length = 0;
+	}
+	/**
+	* Snapshot del estado interno para observabilidad y debugging.
+	*
+	* @returns {Object} stats
+	* @returns {Record<HookEvent, number>} stats.hooks - Conteo de hooks
+	*   registrados por evento (`beforeLog`, `afterLog`, `onError`).
+	* @returns {number} stats.middlewares - Total de middlewares activos.
+	*
+	* @example
+	* ```ts
+	* const stats = hooks.getStats();
+	* // { hooks: { beforeLog: 2, afterLog: 1, onError: 3 }, middlewares: 1 }
+	* if (stats.hooks.onError === 0) {
+	*   console.warn('Sin handlers onError registrados');
+	* }
+	* ```
+	*/
+	getStats() {
+		return {
+			hooks: {
+				beforeLog: this.hooks.get("beforeLog")?.length || 0,
+				afterLog: this.hooks.get("afterLog")?.length || 0,
+				onError: this.hooks.get("onError")?.length || 0
+			},
+			middlewares: this.middlewares.length
+		};
+	}
+};
+let _defaultHookManager = null;
+/**
+* Devuelve la instancia singleton de {@link HookManager} compartida por todo
+* el proceso. La crea perezosamente en la primera llamada.
+*
+* Pensada como hook manager por defecto del logger; los consumidores que
+* necesiten aislamiento (tests, múltiples loggers con pipelines distintos)
+* deben instanciar su propio `new HookManager()` en lugar de usar este shared.
+*
+* @returns {HookManager} La instancia singleton.
+*
+* @example
+* ```ts
+* import { getDefaultHookManager } from '@mks2508/better-logger/hooks';
+*
+* getDefaultHookManager().on('onError', async (entry) => {
+*   telemetry.capture(entry.error);
+* });
+* ```
+*
+* @see {@link HookManager}
+*/
+function getDefaultHookManager() {
+	if (!_defaultHookManager) _defaultHookManager = new HookManager();
+	return _defaultHookManager;
+}
+//#endregion
+//#region src/hooks/HookBridge.ts
+/**
+* Crea una instancia de {@link HookBridge}.
+*
+* @internal
+*/
+function createHookBridge() {
+	const hookManager = new HookManager();
+	return {
+		on(event, callback, priority) {
+			return hookManager.on(event, callback, priority);
+		},
+		once(event, callback, priority) {
+			return hookManager.once(event, callback, priority);
+		},
+		off(event, callback) {
+			return hookManager.off(event, callback);
+		},
+		use(middleware, priority) {
+			return hookManager.use(middleware, priority);
+		},
+		getHookManager() {
+			return hookManager;
+		}
+	};
+}
+//#endregion
+export { HookManager as n, getDefaultHookManager as r, createHookBridge as t };
+
+//# sourceMappingURL=HookBridge-CI2PH79S.js.map

package/dist/chunks/HookBridge-CI2PH79S.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HookBridge-CI2PH79S.js","names":[],"sources":["../../src/hooks/HookManager.ts","../../src/hooks/HookBridge.ts"],"sourcesContent":["import type {\n    HookLogEntry,\n    HookEvent,\n    HookCallback,\n    MiddlewareFn,\n    HookRegistration,\n    MiddlewareRegistration,\n    IHookManager\n} from '../types/index.js';\n\n/**\n * Profundidad máxima de reentrancia permitida para el evento `onError`.\n *\n * Cuando un hook registrado para `onError` lanza una excepción, el manager\n * re-emite el error como un nuevo evento `onError`, lo que podría entrar en\n * un bucle infinito. Este límite corta la cadena tras N niveles de anidamiento\n * y deja caer el entry al console para no acaparar el event loop.\n *\n * @internal Constantante de implementación; no forma parte de la API pública.\n */\nconst MAX_ONERROR_DEPTH = 5;\n\n/**\n * Genera un identificador corto y único para cada registro de hook/middleware.\n *\n * Combina timestamp con un segmento aleatorio base36. Suficiente para\n * desambiguar registros dentro de un mismo proceso; no es un UUID criptográfico.\n *\n * @internal Helper interno; no es API pública.\n * @returns {string} ID tipo `<epoch>-<random9>`.\n */\nfunction generateId(): string {\n    return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;\n}\n\n/**\n * Implementación por defecto de {@link IHookManager} que orquesta el ciclo de\n * vida de los hooks del logger: `beforeLog`, `afterLog` y `onError`.\n *\n * Permite:\n * - Registrar callbacks por evento con **prioridad** (mayor número = se\n *   ejecuta primero; las registraciones se ordenan descendentemente).\n * - Encadenar middlewares sobre el entry previo al dispatch.\n * - Propagar mutaciones: cada hook puede retornar un partial de\n *   {@link HookLogEntry} que se mergea al entry actual antes del siguiente hook.\n * - Acotar la recursión de `onError` con un guard de profundidad\n *   ({@link MAX_ONERROR_DEPTH}) para que un hook que lanza no loopée para\n *   siempre.\n *\n * El flujo típico lo orquesta el logger vía {@link process} (emite `beforeLog`\n * + ejecuta middlewares) y {@link afterProcess} (emite `afterLog`).\n *\n * @example\n * ```ts\n * const hooks = new HookManager();\n *\n * // Mayor prioridad => corre primero\n * hooks.on('beforeLog', (entry) => {\n *   return { ...entry, attributes: { ...entry.attributes, traced: true } };\n * }, 90);\n *\n * hooks.on('afterLog', (entry) => {\n *   metrics.increment('log_emitted', { level: entry.level });\n * });\n *\n * hooks.on('onError', (entry) => {\n *   telemetry.capture(entry.error);\n * });\n * ```\n *\n * @example\n * ```ts\n * // Middleware que añade timestamp si falta y delega al siguiente\n * hooks.use(async (entry, next) => {\n *   if (!entry.time) entry.time = Date.now();\n *   await next();\n * });\n * ```\n *\n * @see {@link IHookManager}\n * @see {@link HookEvent}\n */\nexport class HookManager implements IHookManager {\n    private hooks: Map<HookEvent, HookRegistration[]> = new Map();\n    private middlewares: MiddlewareRegistration[] = [];\n    /**\n     * Lleva el conteo de la profundidad de recursión actual por cada evento de\n     * hook, para que las cadenas de `onError` que lanzan excepciones no puedan\n     * loopéar para siempre. Se resetea cuando el `emit` externo retorna.\n     */\n    private _onErrorDepth: Map<HookEvent, number> = new Map();\n\n    constructor() {\n        this.hooks.set('beforeLog', []);\n        this.hooks.set('afterLog', []);\n        this.hooks.set('onError', []);\n    }\n\n    /**\n     * Registra un callback persistente para un evento. Se ejecuta en cada\n     * emisión hasta que se cancele con la función devuelta o con {@link off}.\n     *\n     * Los hooks se ordenan por `priority` **descendente**: mayor número =\n     * se ejecuta primero. Misma prioridad respeta el orden de registro.\n     *\n     * @param event - Uno de `'beforeLog' | 'afterLog' | 'onError'`.\n     * @param callback - Función asíncrona que recibe el {@link HookLogEntry}\n     *   actual y puede retornar un partial para mutar el entry que verán los\n     *   hooks siguientes.\n     * @param priority - Peso de ordenamiento. Default `50`. Mayor = primero.\n     * @returns {() => void} Función de cancelación; llamarla desregistra el hook.\n     *\n     * @example\n     * ```ts\n     * const off = hooks.on('beforeLog', async (entry) => {\n     *   return { attributes: { ...entry.attributes, requestId: getReqId() } };\n     * }, 80);\n     *\n     * // ...en shutdown:\n     * off();\n     * ```\n     *\n     * @see {@link once} para hooks de un solo disparo.\n     * @see {@link off} para desregistro por referencia de callback.\n     */\n    on(event: HookEvent, callback: HookCallback, priority: number = 50): () => void {\n        const registration: HookRegistration = {\n            id: generateId(),\n            event,\n            callback,\n            priority,\n            once: false\n        };\n\n        const hooks = this.hooks.get(event)!;\n        hooks.push(registration);\n        hooks.sort((a, b) => b.priority - a.priority);\n\n        return () => this.removeHook(event, registration.id);\n    }\n\n    /**\n     * Igual que {@link on}, pero el hook se auto-desregistra después del primer\n     * disparo exitoso. Útil para setup one-shot (warm-up de caché, captura del\n     * primer log, ...).\n     *\n     * Si el callback lanza, el hook NO se elimina (la excepción se deriva a\n     * `onError`); la limpieza solo ocurre cuando el callback retorna sin Throw.\n     *\n     * @param event - Evento a escuchar.\n     * @param callback - Handler que se ejecutará una sola vez.\n     * @param priority - Peso de ordenamiento (mayor = primero). Default `50`.\n     * @returns {() => void} Cancelación manual por si se quiere retirar antes\n     *   del primer disparo.\n     *\n     * @example\n     * ```ts\n     * hooks.once('afterLog', async (entry) => {\n     *   console.log('Primer log emitido:', entry.msg);\n     * });\n     * ```\n     *\n     * @see {@link on}\n     */\n    once(event: HookEvent, callback: HookCallback, priority: number = 50): () => void {\n        const registration: HookRegistration = {\n            id: generateId(),\n            event,\n            callback,\n            priority,\n            once: true\n        };\n\n        const hooks = this.hooks.get(event)!;\n        hooks.push(registration);\n        hooks.sort((a, b) => b.priority - a.priority);\n\n        return () => this.removeHook(event, registration.id);\n    }\n\n    /**\n     * Desregistra un hook por referencia de callback. Solo elimina la primera\n     * coincidencia encontrada para el evento.\n     *\n     * Para hooks registrados con {@link on} o {@link once} es preferible usar\n     * la función de cancelación devuelta (que usa el id interno y es O(n) más\n     * directa). `off` es útil cuando se perdió la referencia al cancelador o\n     * cuando se integra con APIs que piden un método `removeListener(cb)`.\n     *\n     * @param event - Evento del que se quiere desregistrar.\n     * @param callback - Misma referencia de función pasada a {@link on}/{@link once}.\n     * @returns {boolean} `true` si se eliminó un hook, `false` si no había match.\n     *\n     * @example\n     * ```ts\n     * const handler = async (entry) => { /* ... *\\/ };\n     * hooks.on('afterLog', handler);\n     * hooks.off('afterLog', handler); // true\n     * ```\n     *\n     * @see {@link on}\n     */\n    off(event: HookEvent, callback: HookCallback): boolean {\n        const hooks = this.hooks.get(event);\n        if (!hooks) return false;\n\n        const index = hooks.findIndex(h => h.callback === callback);\n        if (index >= 0) {\n            hooks.splice(index, 1);\n            return true;\n        }\n        return false;\n    }\n\n    private removeHook(event: HookEvent, id: string): void {\n        const hooks = this.hooks.get(event);\n        if (hooks) {\n            const index = hooks.findIndex(h => h.id === id);\n            if (index >= 0) {\n                hooks.splice(index, 1);\n            }\n        }\n    }\n\n    /**\n     * Registra un middleware que se encadena sobre el {@link HookLogEntry}\n     * **antes** de que se emita el log al resto del pipeline. Los middlewares\n     * corren después del evento `beforeLog` y se ejecutan en cascada vía `next()`.\n     *\n     * Cada middleware recibe `(entry, next)` y debe llamar a `next()` para\n     * ceder el control al siguiente. Si NO llama a `next()`, corta la cadena\n     * (patrón short-circuit).\n     *\n     * Ordenamiento: `priority` descendente (mayor = primero), igual que los\n     * hooks. La secuencia respetada es la del sort, no la del orden de\n     * llamada a `use`.\n     *\n     * @param middleware - Función `(entry, next) => Promise<void>`.\n     * @param priority - Peso de ordenamiento. Default `50`.\n     * @returns {() => void} Función de cancelación para retirar el middleware.\n     *\n     * @example\n     * ```ts\n     * // PII redaction: enmascara passwords antes de loguear\n     * hooks.use(async (entry, next) => {\n     *   if (entry.attributes?.password) {\n     *     entry.attributes.password = '***';\n     *   }\n     *   await next();\n     * }, 90);\n     *\n     * // Short-circuit: si es level=debug y env=prod, no baja\n     * const stop = hooks.use(async (entry, next) => {\n     *   if (entry.level === 'debug' && ENV === 'production') return;\n     *   await next();\n     * }, 100);\n     * ```\n     *\n     * @see {@link process} para el orquestador que ejecuta la cadena.\n     */\n    use(middleware: MiddlewareFn, priority: number = 50): () => void {\n        const registration: MiddlewareRegistration = {\n            id: generateId(),\n            fn: middleware,\n            priority\n        };\n\n        this.middlewares.push(registration);\n        this.middlewares.sort((a, b) => b.priority - a.priority);\n\n        return () => {\n            const index = this.middlewares.findIndex(m => m.id === registration.id);\n            if (index >= 0) {\n                this.middlewares.splice(index, 1);\n            }\n        };\n    }\n\n    /**\n     * Emite un evento a todos sus hooks registrados, en orden de prioridad, y\n     * retorna el entry resultante tras aplicar todos los mutations.\n     *\n     * Cada hook puede retornar un partial de {@link HookLogEntry}; ese partial\n     * se mergea sobre el entry actual antes de invocar al siguiente hook, así\n     * los hooks se encadenan como una pipeline de transformaciones.\n     *\n     * Manejo de errores:\n     * - Si un hook de `beforeLog`/`afterLog` lanza, la excepción se captura y\n     *   se re-emite como evento `onError` con el campo `error` poblado.\n     * - Si un hook de `onError` lanza, **NO** se re-emite (rompería el ciclo);\n     *   se loguea a `console.error` y se traga.\n     * - Guard de reentrancia: si `onError` se re-entra más de\n     *   {@link MAX_ONERROR_DEPTH} veces, se corta y se loguea el entry al\n     *   console. Previene loops infinitos por errores en cascada.\n     *\n     * Los hooks marcados como `once` se eliminan tras un disparo exitoso.\n     *\n     * @param event - Evento a emitir.\n     * @param entry - Entry inicial; no se muta in-place (se clona por nivel).\n     * @returns {Promise<HookLogEntry>} Entry transformado tras todos los hooks.\n     *\n     * @example\n     * ```ts\n     * const enriched = await hooks.emit('beforeLog', rawEntry);\n     * // enriched.attributes puede traer merges de varios hooks\n     * ```\n     *\n     * @see {@link on}\n     * @see {@link once}\n     * @see {@link MAX_ONERROR_DEPTH}\n     */\n    async emit(event: HookEvent, entry: HookLogEntry): Promise<HookLogEntry> {\n        // Guard de reentrancia. Sin esto, un hook de onError que lance\n        // re-entraría a emit('onError', ...) y loopearía para siempre o\n        // recursaría hasta hacer volar el stack. Permitimos un burst pequeño\n        // (MAX_ONERROR_DEPTH) para que el fan-out legítimo siga funcionando,\n        // pero cortamos el ciclo.\n        const depth = (this._onErrorDepth.get(entry.hookEvent ?? event) ?? 0);\n        if (event === 'onError' && depth >= MAX_ONERROR_DEPTH) {\n            // eslint-disable-next-line no-console\n            console.error('HookManager: onError recursion limit reached, dropping entry:', entry);\n            return entry;\n        }\n        this._onErrorDepth.set(event, depth + 1);\n\n        try {\n            const hooks = this.hooks.get(event) || [];\n            let currentEntry = { ...entry };\n            const toRemove: string[] = [];\n\n            for (const hook of hooks) {\n                try {\n                    const result = await hook.callback(currentEntry);\n                    if (result) {\n                        currentEntry = { ...currentEntry, ...result };\n                    }\n                    if (hook.once) {\n                        toRemove.push(hook.id);\n                    }\n                } catch (error) {\n                    if (event !== 'onError') {\n                        await this.emit('onError', {\n                            ...currentEntry,\n                            error: error instanceof Error ? error : new Error(String(error)),\n                            hookEvent: event\n                        });\n                    } else {\n                        // Un hook de onError lanzó — se loguea al console (single shot)\n                        // sin emitir otro onError (lo que recursaría).\n                        // eslint-disable-next-line no-console\n                        console.error('HookManager: onError hook threw, swallowed to break recursion:', error);\n                    }\n                }\n            }\n\n            toRemove.forEach(id => this.removeHook(event, id));\n            return currentEntry;\n        } finally {\n            this._onErrorDepth.set(event, depth);\n        }\n    }\n\n    /**\n     * Orquesta el pipeline pre-emit de un log. Orden de ejecución:\n     *\n     * 1. Emite `beforeLog` (todos sus hooks corren en orden de prioridad y\n     *    pueden mutar el entry vía return partial).\n     * 2. Si hay middlewares registrados ({@link use}), los ejecuta en cascada\n     *    sobre el entry ya enriquecido por los hooks de `beforeLog`.\n     *\n     * Es el punto de entrada que el logger invoca **antes** de despachar el\n     * record a los transports. El entry devuelto es el que finalmente se loguea.\n     *\n     * No emite `afterLog`; para eso usar {@link afterProcess} una vez que el\n     * dispatch al transport haya terminado.\n     *\n     * @param entry - Entry crudo entrante al pipeline.\n     * @returns {Promise<HookLogEntry>} Entry final listo para mandar a transports.\n     *\n     * @example\n     * ```ts\n     * const processed = await hooks.process(rawEntry);\n     * await transport.write(processed);\n     * await hooks.afterProcess(processed);\n     * ```\n     *\n     * @see {@link afterProcess}\n     * @see {@link use}\n     */\n    async process(entry: HookLogEntry): Promise<HookLogEntry> {\n        let currentEntry = { ...entry };\n\n        currentEntry = await this.emit('beforeLog', currentEntry);\n\n        if (this.middlewares.length > 0) {\n            let index = 0;\n\n            const executeNext = async (): Promise<void> => {\n                if (index < this.middlewares.length) {\n                    const middleware = this.middlewares[index++];\n                    if (middleware) {\n                        await middleware.fn(currentEntry, executeNext);\n                    }\n                }\n            };\n\n            await executeNext();\n        }\n\n        return currentEntry;\n    }\n\n    /**\n     * Emite el evento `afterLog` con el entry ya procesado y dispatcheado a\n     * los transports. Pensado para side-effects post-log: métricas, audit\n     * trail, flush de buffers externos, etc.\n     *\n     * Los hooks de `afterLog` pueden retornar un partial pero el entry ya se\n     * ha publicado, así que la mutación no tiene efecto sobre el log emitido;\n     * solo queda disponible en el return de {@link emit}, que aquí se descarta.\n     *\n     * @param entry - Entry final (mismo objeto devuelto por {@link process}).\n     * @returns {Promise<void>} Resuelve cuando todos los hooks terminaron.\n     *\n     * @example\n     * ```ts\n     * hooks.on('afterLog', async (entry) => {\n     *   metrics.increment('logs_total', { level: entry.level });\n     * });\n     *\n     * const processed = await hooks.process(rawEntry);\n     * await transport.write(processed);\n     * await hooks.afterProcess(processed); // dispara métricas\n     * ```\n     *\n     * @see {@link process}\n     */\n    async afterProcess(entry: HookLogEntry): Promise<void> {\n        await this.emit('afterLog', entry);\n    }\n\n    /**\n     * Vacía todos los hooks y middlewares registrados. Útil para resetear el\n     * estado entre tests o en hot-reload.\n     *\n     * Afecta a los tres eventos (`beforeLog`, `afterLog`, `onError`) y a la\n     * pila de middlewares. Las funciones de cancelación devueltas por\n     * {@link on}/{@link once}/{@link use} se vuelven no-ops pero pueden\n     * llamarse sin error.\n     *\n     * @example\n     * ```ts\n     * afterEach(() => hooks.clear());\n     * ```\n     */\n    clear(): void {\n        this.hooks.forEach(hooks => hooks.length = 0);\n        this.middlewares.length = 0;\n    }\n\n    /**\n     * Snapshot del estado interno para observabilidad y debugging.\n     *\n     * @returns {Object} stats\n     * @returns {Record<HookEvent, number>} stats.hooks - Conteo de hooks\n     *   registrados por evento (`beforeLog`, `afterLog`, `onError`).\n     * @returns {number} stats.middlewares - Total de middlewares activos.\n     *\n     * @example\n     * ```ts\n     * const stats = hooks.getStats();\n     * // { hooks: { beforeLog: 2, afterLog: 1, onError: 3 }, middlewares: 1 }\n     * if (stats.hooks.onError === 0) {\n     *   console.warn('Sin handlers onError registrados');\n     * }\n     * ```\n     */\n    getStats(): { hooks: Record<HookEvent, number>; middlewares: number } {\n        return {\n            hooks: {\n                beforeLog: this.hooks.get('beforeLog')?.length || 0,\n                afterLog: this.hooks.get('afterLog')?.length || 0,\n                onError: this.hooks.get('onError')?.length || 0\n            },\n            middlewares: this.middlewares.length\n        };\n    }\n}\n\nlet _defaultHookManager: HookManager | null = null;\n\n/**\n * Devuelve la instancia singleton de {@link HookManager} compartida por todo\n * el proceso. La crea perezosamente en la primera llamada.\n *\n * Pensada como hook manager por defecto del logger; los consumidores que\n * necesiten aislamiento (tests, múltiples loggers con pipelines distintos)\n * deben instanciar su propio `new HookManager()` en lugar de usar este shared.\n *\n * @returns {HookManager} La instancia singleton.\n *\n * @example\n * ```ts\n * import { getDefaultHookManager } from '@mks2508/better-logger/hooks';\n *\n * getDefaultHookManager().on('onError', async (entry) => {\n *   telemetry.capture(entry.error);\n * });\n * ```\n *\n * @see {@link HookManager}\n */\nexport function getDefaultHookManager(): HookManager {\n    if (!_defaultHookManager) {\n        _defaultHookManager = new HookManager();\n    }\n    return _defaultHookManager;\n}\n","/**\n * @fileoverview HookBridge — facade de HookManager.\n * Encapsula registro de hooks, middleware pipeline y emisión de eventos.\n *\n * @internal\n */\n\nimport type { HookEvent, HookCallback, MiddlewareFn } from '../types/index.js';\nimport { HookManager } from './index.js';\n\n/**\n * Bridge para la gestión de hooks y middleware.\n *\n * @internal\n */\nexport interface HookBridge {\n    /** Registra un hook para un evento. Devuelve función de unsubscribe. */\n    on(event: HookEvent, callback: HookCallback, priority?: number): () => void;\n    /** Registra un hook one-time. Devuelve función de unsubscribe. */\n    once(event: HookEvent, callback: HookCallback, priority?: number): () => void;\n    /** Elimina un hook registrado. Devuelve `true` si se eliminó. */\n    off(event: HookEvent, callback: HookCallback): boolean;\n    /** Añade middleware al pipeline. Devuelve función de unsubscribe. */\n    use(middleware: MiddlewareFn, priority?: number): () => void;\n    /** Devuelve el HookManager subyacente. */\n    getHookManager(): HookManager;\n}\n\n/**\n * Crea una instancia de {@link HookBridge}.\n *\n * @internal\n */\nexport function createHookBridge(): HookBridge {\n    const hookManager = new HookManager();\n\n    return {\n        on(event: HookEvent, callback: HookCallback, priority?: number): () => void {\n            return hookManager.on(event, callback, priority);\n        },\n\n        once(event: HookEvent, callback: HookCallback, priority?: number): () => void {\n            return hookManager.once(event, callback, priority);\n        },\n\n        off(event: HookEvent, callback: HookCallback): boolean {\n            return hookManager.off(event, callback);\n        },\n\n        use(middleware: MiddlewareFn, priority?: number): () => void {\n            return hookManager.use(middleware, priority);\n        },\n\n        getHookManager(): HookManager {\n            return hookManager;\n        }\n    };\n}\n"],"mappings":"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"}

package/dist/chunks/{LogContext-L7HzynFw.cjs → LogContext-BaMXleWj.cjs}

@@ -1,10 +1,25 @@
 //#region src/context/LogContext.ts
 const alsInstance = typeof AsyncLocalStorage !== "undefined" ? new AsyncLocalStorage() : void 0;
 /**
-* Creates a LogContext instance.
+* Factory que crea una instancia de {@link LogContext}.
 *
-* @param options - Configuration options
-* @returns A LogContext instance
+* @param options - Configuración (ver {@link ILogContextOptions})
+* @returns Una instancia de LogContext lista para usar
+*
+* @example
+* const logContext = createLogContext({
+*   childLoggerFactory: (cfg) => new Logger(cfg),
+*   initialContext: { service: 'orders-api' },
+*   initialResource: { serviceName: 'orders-api', environment: 'prod' }
+* });
+*
+* // Child inmutable con contexto persistente
+* const requestLog = logContext.child({ requestId: 'abc-123' });
+*
+* // Scope transitorio vía ALS (Node; en browser sin ALS es no-op)
+* logContext.withContext({ traceId: 't-9' }, () => {
+*   requestLog.info('procesando orden');
+* });
 */
 function createLogContext(options) {
 	let context = { ...options.initialContext };
@@ -87,4 +102,4 @@ Object.defineProperty(exports, "createLogContext", {
 	}
 });
 
-//# sourceMappingURL=LogContext-L7HzynFw.cjs.map
+//# sourceMappingURL=LogContext-BaMXleWj.cjs.map

package/dist/chunks/LogContext-BaMXleWj.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"LogContext-BaMXleWj.cjs","names":[],"sources":["../../src/context/LogContext.ts"],"sourcesContent":["/**\n * @fileoverview Bridge de LogContext — gestión de MDC (Mapped Diagnostic Context).\n *\n * Encapsula el contexto estructurado por logger, la creación de child loggers y\n * el merge de resource OTel en cada record emitido.\n *\n * Modelo de API:\n * - `withContext(bindings, fn?)` — si se pasa `fn`, lo ejecuta dentro de un\n *   scope de AsyncLocalStorage mergeando `bindings`. Sin `fn`: no-op (shim de\n *   backwards compat para la vieja forma de setter).\n * - `withContextAsync(bindings, fn)` — variante async callback.\n * - `child(bindings)` — inmutable (patrón canónico de MDC).\n * - Feature-detect de AsyncLocalStorage; en browser sin ALS es no-op.\n */\n\nimport type { ILogResourceRef } from '../types/index.js';\nimport type { LoggerConfig } from '../types/index.js';\n\n/**\n * Snapshot del contexto bound. Lo retorna {@link LogContext.getContext}.\n *\n * Es `Readonly` para marcar contractually que el objeto devuelto es una shallow\n * copy: mutarlo no afecta a los records que emitan futuras llamadas de log.\n */\nexport type ContextSnapshot = Readonly<Record<string, unknown>>;\n\n/**\n * Tipo de la factory function para crear instancias child de Logger.\n *\n * Se inyecta en LogContext para que `child()` pueda instanciar nuevos loggers\n * sin introducir un import circular entre `Logger.ts` y `LogContext.ts`.\n * Retorna `unknown` — la clase Logger concreta la maneja el caller, y la\n * instancia devuelta tiene su campo `context` escrito por LogContext tras la\n * creación.\n */\nexport type ChildLoggerFactory = (config: Partial<LoggerConfig>) => unknown;\n\n/**\n * Shape mínima de una instancia de Logger que LogContext necesita ver.\n *\n * Evita dependencias circulares entre LogContext y Logger. El campo\n * `_parentContextRecord` lo setea el Logger padre después de que\n * `LogContext.child()` retorna, estableciendo la cadena de contextos.\n */\nexport interface ChildLoggerShape {\n    _parentContextRecord?: Record<string, unknown>;\n    /** Campo legacy — ya no es la fuente canónica del contexto. */\n    context?: Record<string, unknown>;\n}\n\n/**\n * Options que se pasan a {@link createLogContext}.\n */\nexport interface ILogContextOptions {\n    /** Pares key-value iniciales del contexto. */\n    initialContext?: Record<string, unknown>;\n    /** Factory para crear instancias child de logger. */\n    childLoggerFactory: ChildLoggerFactory;\n    /** Resource OTel inicial a mergear en cada record emitido. */\n    initialResource?: Partial<ILogResourceRef>;\n    /**\n     * Retorna el record de contexto mergeado del logger padre en el momento\n     * de creación del child. Lo usa `_getContextRecord()` para construir la\n     * cadena de contextos.\n     * @internal\n     */\n    getParentContextRecord?: () => Record<string, unknown>;\n    /**\n     * Instancia de AsyncLocalStorage a usar para el scoping de `withContext`.\n     * @internal\n     */\n    alsInstance?: ALS;\n}\n\n/**\n * Contrato que retorna {@link createLogContext}.\n *\n * Fachada de MDC (Mapped Diagnostic Context) por logger. Combina tres fuentes\n * de contexto:\n * - **base inmutable** vía `child()` (snapshot capturado al crear el child),\n * - **scope transitorio** vía `withContext()` / `withContextAsync()` sobre\n *   AsyncLocalStorage,\n * - **resource OTel** mergeado en cada record.\n *\n * En entornos browser sin `AsyncLocalStorage`, las variantes `withContext*`\n * degradan a no-op: ejecutan `fn` sin scoping (o lo skipan si no hay `fn`).\n * `child()` sigue operativo en browser porque no depende de ALS.\n */\nexport interface LogContext {\n    /**\n     * Snapshot actual del contexto bound.\n     *\n     * @returns Copia inmutable (shallow) del contexto; mutarla no afecta a los\n     * records que emitan futuras llamadas de log.\n     *\n     * @example\n     * const ctx = logContext.getContext();\n     * console.log(ctx.requestId); // 'abc-123'\n     */\n    getContext(): ContextSnapshot;\n\n    /**\n     * Ejecuta `fn` dentro de un scope de AsyncLocalStorage donde `bindings`\n     * se mergean al contexto para todas las llamadas de log dentro de `fn`.\n     *\n     * Si no se pasa `fn` (la vieja forma de setter), es no-op por backwards\n     * compatibility. Para binding persistente prefiere `child()`; para\n     * callbacks async usa `withContextAsync()`.\n     *\n     * **Browser fallback**: sin ALS, ejecuta `fn` directamente sin scoping\n     * (los bindings NO se mergean). Si tampoco hay `fn`, retorna `undefined`.\n     *\n     * @param bindings - Pares key-value a attachar durante la ejecución de `fn`\n     * @param fn - Función sincrónica opcional a ejecutar bajo el scope ALS\n     * @returns El valor de retorno de `fn`, o `undefined` si no se pasa `fn`\n     *\n     * @example\n     * logContext.withContext({ requestId: 'abc-123' }, () => {\n     *   logger.info('procesando'); // el record lleva requestId=abc-123\n     * });\n     * // fuera de fn: requestId ya no está presente en próximos logs\n     *\n     * @see {@link LogContext.withContextAsync} para callbacks async\n     * @see {@link LogContext.child} para binding persistente inmutable (sin ALS)\n     */\n    withContext<R>(bindings: Record<string, unknown>, fn?: () => R): R | undefined;\n\n    /**\n     * Variante async de {@link withContext}. Ejecuta `fn` dentro de un scope\n     * de AsyncLocalStorage para que los bindings queden disponibles a todas las\n     * llamadas de log async dentro de `fn` (incluso tras `await`).\n     *\n     * **Browser fallback**: sin ALS, ejecuta `fn` directamente sin scoping.\n     *\n     * @param bindings - Pares key-value a attachar durante la ejecución de `fn`\n     * @param fn - Función async a ejecutar bajo el scope ALS\n     * @returns El Promise retornado por `fn`\n     *\n     * @example\n     * await logContext.withContextAsync({ traceId }, async () => {\n     *   const user = await fetchUser();\n     *   logger.info('user cargado', { id: user.id });\n     *   // el record lleva el traceId aunque el log ocurra tras un await\n     * });\n     */\n    withContextAsync<R>(bindings: Record<string, unknown>, fn: () => Promise<R>): Promise<R>;\n\n    /**\n     * Droppea todas las keys del contexto bound. Tras esta llamada, los\n     * records emitidos ya no llevan `attributes` hasta que\n     * {@link withContext} o {@link child} restablezcan uno.\n     *\n     * @returns La misma instancia de LogContext, ahora sin contexto\n     *\n     * @example\n     * logContext.clearContext();\n     * logger.info('limpio'); // sin attributes\n     */\n    clearContext(): this;\n\n    /**\n     * Actualiza el resource OTel por defecto (service.name, version,\n     * deployment.environment, ...).\n     *\n     * Se persiste en el campo `resource` de cada record emitido, salvo que el\n     * propio record lo overridee.\n     *\n     * @param resource - Resource OTel parcial a mergear con el actual\n     * @returns La misma instancia de LogContext, para encadenar calls\n     *\n     * @example\n     * logContext.setResource({ serviceName: 'api-gateway', environment: 'prod' });\n     */\n    setResource(resource: Partial<ILogResourceRef>): this;\n\n    /**\n     * Devuelve una copia inmutable de este logger con el contexto extra bound.\n     *\n     * Las llamadas futuras sobre el child emiten con el contexto mergeado, sin\n     * mutar al padre — patrón canónico de MDC.\n     *\n     * A diferencia de {@link withContext}, **no involucra AsyncLocalStorage**:\n     * el binding es persistente y queda capturado en el snapshot del child al\n     * crearse. Por eso `child()` es operativo también en browser sin ALS.\n     *\n     * Los bindings transitorios de ALS activos en el momento de `child()` NO\n     * se bakean en el child — solo se captura el contexto base. ALS se aplica\n     * fresco en cada dispatch vía `_getContextRecord()`.\n     *\n     * @param extra - Pares key-value a attachar (requestId, userId, ...)\n     * @returns Un nuevo Logger con el contexto mergeado\n     *\n     * @example\n     * const requestLog = logContext.child({ requestId: 'abc-123' });\n     * requestLog.info('inicio');   // siempre lleva requestId=abc-123\n     * requestLog.info('fin');\n     * // el logger padre no se ve afectado por estos bindings\n     *\n     * @see {@link LogContext.withContext} para scoping transitorio (ALS)\n     */\n    child(extra: Record<string, unknown>): ChildLoggerShape;\n\n    /**\n     * Record de contexto interno. Expuesto para el ensamblado de TransportRecord\n     * (base + overlay ALS si hay store activo).\n     * @internal\n     */\n    _getContextRecord(): Record<string, unknown>;\n    /**\n     * Retorna el contexto base SIN el overlay de ALS.\n     *\n     * Lo usa `Logger.child()` para capturar el snapshot del contexto padre al\n     * crear un child logger, garantizando que el binding ALS transitorio no\n     * se bakeé en el child.\n     * @internal\n     */\n    _getBaseContextRecord(): Record<string, unknown>;\n    /**\n     * Record de resource interno. Expuesto para el ensamblado de TransportRecord.\n     * @internal\n     */\n    _getResource(): Partial<ILogResourceRef> | undefined;\n    /**\n     * Retorna el store actual de AsyncLocalStorage, si ALS está activo en el\n     * call stack corriente.\n     * @internal\n     */\n    _getAlsStore(): Record<string, unknown> | undefined;\n}\n\n// AsyncLocalStorage type (Node 14+, undefined in browser)\ntype ALS = {\n    run<R>(store: Record<string, unknown>, fn: () => R): R;\n    getStore(): Record<string, unknown> | undefined;\n};\ndeclare const AsyncLocalStorage: new () => ALS;\n\n// Feature-detect AsyncLocalStorage\nconst hasALS = typeof AsyncLocalStorage !== 'undefined';\nconst alsInstance: ALS | undefined = hasALS ? new AsyncLocalStorage() : undefined;\n\n/**\n * Factory que crea una instancia de {@link LogContext}.\n *\n * @param options - Configuración (ver {@link ILogContextOptions})\n * @returns Una instancia de LogContext lista para usar\n *\n * @example\n * const logContext = createLogContext({\n *   childLoggerFactory: (cfg) => new Logger(cfg),\n *   initialContext: { service: 'orders-api' },\n *   initialResource: { serviceName: 'orders-api', environment: 'prod' }\n * });\n *\n * // Child inmutable con contexto persistente\n * const requestLog = logContext.child({ requestId: 'abc-123' });\n *\n * // Scope transitorio vía ALS (Node; en browser sin ALS es no-op)\n * logContext.withContext({ traceId: 't-9' }, () => {\n *   requestLog.info('procesando orden');\n * });\n */\nexport function createLogContext(options: ILogContextOptions): LogContext {\n    let context: Record<string, unknown> = { ...options.initialContext };\n    let resource: Partial<ILogResourceRef> | undefined = options.initialResource\n        ? { ...options.initialResource }\n        : undefined;\n\n    // Use provided ALS instance or fall back to module-level (browser fallback)\n    const als = options.alsInstance ?? alsInstance;\n\n    return {\n        getContext(): ContextSnapshot {\n            return { ...context };\n        },\n\n        withContext<R>(bindings: Record<string, unknown>, fn?: () => R): R | undefined {\n            // No-op without AsyncLocalStorage (browser) — warn once\n            if (!als) {\n                if (fn) return fn();\n                return undefined;\n            }\n            // No fn: backwards-compat no-op setter shim\n            if (!fn) return undefined;\n            // Run fn within AsyncLocalStorage scope\n            const merged = { ...context, ...bindings };\n            return als.run(merged, fn);\n        },\n\n        async withContextAsync<R>(bindings: Record<string, unknown>, fn: () => Promise<R>): Promise<R> {\n            if (!als) return fn();\n            const merged = { ...context, ...bindings };\n            return als.run(merged, fn);\n        },\n\n        clearContext(): typeof this {\n            context = {};\n            return this;\n        },\n\n        setResource(res: Partial<ILogResourceRef>): typeof this {\n            resource = { ...resource, ...res };\n            return this;\n        },\n\n        child(_extra: Record<string, unknown>): ChildLoggerShape {\n            // Creates the child logger via factory. Captures the current\n            // _getBaseContextRecord() snapshot (parent context WITHOUT ALS) at\n            // child-creation time. ALS is transient and should not be baked into\n            // the child's _parentContextRecord — it is applied fresh at dispatch time.\n            // Note: _extra (bindings) are stored by Logger.child() as _bindings.\n            const snapshot = this._getBaseContextRecord();\n            const childLogger = options.childLoggerFactory({}) as ChildLoggerShape;\n            // Store on childLogger for Logger.child() to pick up\n            (childLogger as unknown as Record<string, unknown>)['__parentSnapshot'] = snapshot;\n            return childLogger;\n        },\n\n        _getContextRecord(): Record<string, unknown> {\n            // Returns the full merged context for dispatch purposes.\n            // Base (parent snapshot + own context) plus ALS overlay if active.\n            const base = this._getBaseContextRecord();\n            const alsContext = als?.getStore();\n            if (alsContext && Object.keys(alsContext).length > 0) {\n                return { ...base, ...alsContext };\n            }\n            return base;\n        },\n\n        _getBaseContextRecord(): Record<string, unknown> {\n            // Returns parent context chain + own context (NO ALS overlay).\n            // ALS is applied by _getContextRecord() as a live overlay.\n            let base: Record<string, unknown> = {};\n            const parentRecord = options.getParentContextRecord?.() ?? null;\n            if (parentRecord && Object.keys(parentRecord).length > 0) {\n                base = parentRecord;\n            } else if (Object.keys(context).length > 0) {\n                base = context;\n            }\n            if (Object.keys(context).length > 0) {\n                base = { ...base, ...context };\n            }\n            return base;\n        },\n\n        _getResource(): Partial<ILogResourceRef> | undefined {\n            return resource;\n        },\n\n        _getAlsStore(): Record<string, unknown> | undefined {\n            return als?.getStore();\n        }\n    };\n}\n"],"mappings":";AA+OA,MAAM,cADS,OAAO,sBAAsB,cACE,IAAI,kBAAkB,IAAI,KAAA;;;;;;;;;;;;;;;;;;;;;;AAuBxE,SAAgB,iBAAiB,SAAyC;CACtE,IAAI,UAAmC,EAAE,GAAG,QAAQ,eAAe;CACnE,IAAI,WAAiD,QAAQ,kBACvD,EAAE,GAAG,QAAQ,gBAAgB,IAC7B,KAAA;CAGN,MAAM,MAAM,QAAQ,eAAe;CAEnC,OAAO;EACH,aAA8B;GAC1B,OAAO,EAAE,GAAG,QAAQ;EACxB;EAEA,YAAe,UAAmC,IAA6B;GAE3E,IAAI,CAAC,KAAK;IACN,IAAI,IAAI,OAAO,GAAG;IAClB;GACJ;GAEA,IAAI,CAAC,IAAI,OAAO,KAAA;GAEhB,MAAM,SAAS;IAAE,GAAG;IAAS,GAAG;GAAS;GACzC,OAAO,IAAI,IAAI,QAAQ,EAAE;EAC7B;EAEA,MAAM,iBAAoB,UAAmC,IAAkC;GAC3F,IAAI,CAAC,KAAK,OAAO,GAAG;GACpB,MAAM,SAAS;IAAE,GAAG;IAAS,GAAG;GAAS;GACzC,OAAO,IAAI,IAAI,QAAQ,EAAE;EAC7B;EAEA,eAA4B;GACxB,UAAU,CAAC;GACX,OAAO;EACX;EAEA,YAAY,KAA4C;GACpD,WAAW;IAAE,GAAG;IAAU,GAAG;GAAI;GACjC,OAAO;EACX;EAEA,MAAM,QAAmD;GAMrD,MAAM,WAAW,KAAK,sBAAsB;GAC5C,MAAM,cAAc,QAAQ,mBAAmB,CAAC,CAAC;GAEjD,YAAoD,sBAAsB;GAC1E,OAAO;EACX;EAEA,oBAA6C;GAGzC,MAAM,OAAO,KAAK,sBAAsB;GACxC,MAAM,aAAa,KAAK,SAAS;GACjC,IAAI,cAAc,OAAO,KAAK,UAAU,CAAC,CAAC,SAAS,GAC/C,OAAO;IAAE,GAAG;IAAM,GAAG;GAAW;GAEpC,OAAO;EACX;EAEA,wBAAiD;GAG7C,IAAI,OAAgC,CAAC;GACrC,MAAM,eAAe,QAAQ,yBAAyB,KAAK;GAC3D,IAAI,gBAAgB,OAAO,KAAK,YAAY,CAAC,CAAC,SAAS,GACnD,OAAO;QACJ,IAAI,OAAO,KAAK,OAAO,CAAC,CAAC,SAAS,GACrC,OAAO;GAEX,IAAI,OAAO,KAAK,OAAO,CAAC,CAAC,SAAS,GAC9B,OAAO;IAAE,GAAG;IAAM,GAAG;GAAQ;GAEjC,OAAO;EACX;EAEA,eAAqD;GACjD,OAAO;EACX;EAEA,eAAoD;GAChD,OAAO,KAAK,SAAS;EACzB;CACJ;AACJ"}