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

package/dist/hooks/HookManager.d.ts

@@ -1,26 +1,319 @@
 import type { HookLogEntry, HookEvent, HookCallback, MiddlewareFn, IHookManager } from '../types/index.js';
+/**
+ * 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}
+ */
 export declare class HookManager implements IHookManager {
     private hooks;
     private middlewares;
     /**
-     * Tracks current recursion depth for each hook event so `onError` chains
-     * that throw can't loop forever. Reset when the outer emit returns.
+     * 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.
      */
     private _onErrorDepth;
     constructor();
+    /**
+     * 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: HookEvent, callback: HookCallback, priority?: number): () => void;
+    /**
+     * 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: HookEvent, callback: HookCallback, priority?: number): () => void;
+    /**
+     * 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: HookEvent, callback: HookCallback): boolean;
     private removeHook;
+    /**
+     * 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: MiddlewareFn, priority?: number): () => void;
+    /**
+     * 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}
+     */
     emit(event: HookEvent, entry: HookLogEntry): Promise<HookLogEntry>;
+    /**
+     * 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}
+     */
     process(entry: HookLogEntry): Promise<HookLogEntry>;
+    /**
+     * 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}
+     */
     afterProcess(entry: HookLogEntry): Promise<void>;
+    /**
+     * 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(): void;
+    /**
+     * 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(): {
         hooks: Record<HookEvent, number>;
         middlewares: number;
     };
 }
+/**
+ * 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}
+ */
 export declare function getDefaultHookManager(): HookManager;
 //# sourceMappingURL=HookManager.d.ts.map

package/dist/hooks/HookManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HookManager.d.ts","sourceRoot":"","sources":["../../src/hooks/HookManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,YAAY,EAGZ,YAAY,EACf,MAAM,mBAAmB,CAAC;AAQ3B,qBAAa,WAAY,YAAW,YAAY;IAC5C,OAAO,CAAC,KAAK,CAAiD;IAC9D,OAAO,CAAC,WAAW,CAAgC;IACnD;;;OAGG;IACH,OAAO,CAAC,aAAa,CAAqC;;IAQ1D,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,GAAE,MAAW,GAAG,MAAM,IAAI;IAgB/E,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,GAAE,MAAW,GAAG,MAAM,IAAI;IAgBjF,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO;IAYtD,OAAO,CAAC,UAAU;IAUlB,GAAG,CAAC,UAAU,EAAE,YAAY,EAAE,QAAQ,GAAE,MAAW,GAAG,MAAM,IAAI;IAkB1D,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAkDlE,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAuBnD,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAItD,KAAK,IAAI,IAAI;IAKb,QAAQ,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE;CAUxE;AAID,wBAAgB,qBAAqB,IAAI,WAAW,CAKnD"}
+{"version":3,"file":"HookManager.d.ts","sourceRoot":"","sources":["../../src/hooks/HookManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,YAAY,EAGZ,YAAY,EACf,MAAM,mBAAmB,CAAC;AA2B3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,WAAY,YAAW,YAAY;IAC5C,OAAO,CAAC,KAAK,CAAiD;IAC9D,OAAO,CAAC,WAAW,CAAgC;IACnD;;;;OAIG;IACH,OAAO,CAAC,aAAa,CAAqC;;IAQ1D;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,GAAE,MAAW,GAAG,MAAM,IAAI;IAgB/E;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,GAAE,MAAW,GAAG,MAAM,IAAI;IAgBjF;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO;IAYtD,OAAO,CAAC,UAAU;IAUlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,GAAG,CAAC,UAAU,EAAE,YAAY,EAAE,QAAQ,GAAE,MAAW,GAAG,MAAM,IAAI;IAkBhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAmDxE;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAuBzD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAItD;;;;;;;;;;;;;OAaG;IACH,KAAK,IAAI,IAAI;IAKb;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE;CAUxE;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,IAAI,WAAW,CAKnD"}

package/dist/hooks.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_HookBridge = require("./chunks/HookBridge-CiRfR67f.cjs");
+const require_HookBridge = require("./chunks/HookBridge-C-AvXmPD.cjs");
 exports.HookManager = require_HookBridge.HookManager;
 exports.createHookBridge = require_HookBridge.createHookBridge;
 exports.getDefaultHookManager = require_HookBridge.getDefaultHookManager;

package/dist/hooks.js

@@ -1,2 +1,2 @@
-import { n as HookManager, r as getDefaultHookManager, t as createHookBridge } from "./chunks/HookBridge-SgMmbXZB.js";
+import { n as HookManager, r as getDefaultHookManager, t as createHookBridge } from "./chunks/HookBridge-CI2PH79S.js";
 export { HookManager, createHookBridge, getDefaultHookManager };