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

package/dist/Logger.d.ts

@@ -1,13 +1,15 @@
 /**
  * @fileoverview Logger avanzado con arquitectura modular y API simplificada
- * @version 0.3.0
- * @since 2024
  *
  * Sistema de logging profesional con estilos CSS avanzados, temas adaptativos,
  * badges automáticos, contextos temporales y exportación de datos.
  */
-import type { LogLevel, Verbosity, ThemeVariant, BannerType, LoggerConfig, ILogHandler, StyleOptions } from './types/index.js';
-import { ExportLogHandler } from './handlers/index.js';
+import type { LogLevel, LogTag, Verbosity, ThemeVariant, BannerType, LoggerConfig, ILogHandler, StyleOptions, Bindings, SerializerFn, HookEvent, HookCallback, MiddlewareFn, TransportTarget, TransportRecord, ILogResourceRef, StackInfo } from './types/index.js';
+import { SerializerRegistry } from './serializers/index.js';
+import { HookManager } from './hooks/index.js';
+import { TransportManager } from './transports/index.js';
+import { ScopedLogger, APILogger, ComponentLogger } from './ScopedLogger.js';
+import type { CLILogLevel, ISpinnerHandle, IBoxOptions, ITableOptions } from './types/index.js';
 /**
  * Clase principal Logger con capacidades avanzadas de logging
  *
@@ -32,7 +34,6 @@ import { ExportLogHandler } from './handlers/index.js';
  * auth.info('Usuario intentando login');
  * auth.success('Login exitoso');
  *
- * @since 0.3.0
  */
 export declare class Logger {
     private config;
@@ -40,10 +41,49 @@ export declare class Logger {
     private handlers;
     private timers;
     private groupDepth;
-    private exportHandler?;
     private cliProcessor?;
     private themeChangeListener?;
+    private badgeList;
     private displaySettings;
+    private serializerBridge;
+    private hookBridge;
+    private logContext;
+    private transportBridge;
+    /** Fijado por `success()` para que `log()` salte su propio dispatch. */
+    private _successTagDispatched;
+    private styleManager;
+    /** Controla si las CLI primitives (step, box, header, ...) deben renderizarse. */
+    private _showPrimitives;
+    private terminalBridge;
+    /**
+     * Referencia activa al smart-preset (fijada por `preset()`). Tipada como
+     * `unknown` para mantener limpia la surface pública; la consume
+     * `createStyledOutput`.
+     */
+    private _activePreset?;
+    /**
+     * Nombre del smart-preset activo. Se guarda aparte para que la detección
+     * de cambio de tema pueda re-renderizar sin re-ejecutar el body del preset.
+     */
+    private _activePresetName?;
+    /**
+     * Overrides aplicados por el último `customize()`. Se conservan para que
+     * `createStyledOutput` los lea después.
+     */
+    private _customization?;
+    /**
+     * Bindings propios de este logger (provenientes de llamadas a `child()`).
+     * Source of truth única de la contribución de este logger a la cadena de contexto.
+     * @private
+     */
+    private _bindings;
+    /**
+     * Referencia al record de contexto mergueado del parent en el momento en
+     * que se creó este logger. Junto con `_bindings`, forma la cadena de
+     * contexto. `undefined` para el logger raíz.
+     * @private
+     */
+    private _parentContextRecord;
     /**
      * Crea una nueva instancia del Logger
      *
@@ -75,7 +115,6 @@ export declare class Logger {
      * console.log('Verbosidad actual:', config.verbosity);
      * console.log('Tema actual:', config.theme);
      *
-     * @since 0.3.0
      */
     getConfig(): LoggerConfig;
     /**
@@ -90,7 +129,6 @@ export declare class Logger {
      *   theme: 'cyberpunk'
      * });
      *
-     * @since 0.3.0
      */
     updateConfig(updates: Partial<LoggerConfig>): void;
     /**
@@ -102,7 +140,6 @@ export declare class Logger {
      * logger.setGlobalPrefix('MiApp');
      * logger.info('Iniciado'); // [MiApp] Iniciado
      *
-     * @since 0.3.0
      */
     setGlobalPrefix(prefix: string): void;
     /**
@@ -115,7 +152,6 @@ export declare class Logger {
      * logger.setVerbosity('debug'); // Muestra todos los niveles
      * logger.setVerbosity('silent'); // No muestra nada
      *
-     * @since 0.3.0
      */
     setVerbosity(level: Verbosity): void;
     /**
@@ -128,7 +164,6 @@ export declare class Logger {
      * logger.setTheme('minimal');   // Tema minimalista
      * logger.setTheme('cyberpunk'); // Tema cyberpunk con efectos
      *
-     * @since 0.3.0
      */
     setTheme(theme: ThemeVariant): void;
     /**
@@ -141,9 +176,96 @@ export declare class Logger {
      * logger.setBannerType('unicode');  // Banner con caracteres Unicode
      * logger.setBannerType('animated'); // Banner con animación
      *
-     * @since 0.3.0
      */
     setBannerType(bannerType: BannerType): void;
+    /**
+     * Ejecuta `fn` dentro de un scope AsyncLocalStorage donde `bindings` se
+     * merguean al contexto para todas las llamadas de log dentro de `fn`.
+     *
+     * Sin `fn` (el shape legacy de setter): no-op por backwards compatibility.
+     * Preferir `child()` para bindings persistentes o `withContextAsync()`
+     * para callbacks async.
+     *
+     * @param bindings - Pares key-value a adjuntar durante la ejecución de `fn`
+     * @param fn - Función sincrónica opcional a ejecutar con los bindings en scope
+     * @returns El valor de retorno de `fn`, o `undefined` si no se pasa `fn`
+     *
+     * @example
+     * // Callback sincrónico scoped
+     * logger.withContext({ requestId: 'r-42' }, () => {
+     *   doWork(); // los logs de aquí ven requestId en attributes
+     * });
+     *
+     * @example
+     * // Binding persistente: usar child()
+     * const reqLog = logger.child({ requestId: 'r-42' });
+     * reqLog.info('handling request'); // attributes incluye requestId
+     *
+     * @see {@link child} para una copia inmutable con el contexto mergueado
+     * @see {@link withContextAsync} para la variante con callback async
+     */
+    withContext<R>(bindings: Record<string, unknown>, fn?: () => R): R | undefined;
+    /**
+     * Variante async de `withContext`. Ejecuta `fn` dentro de un scope
+     * AsyncLocalStorage para que los bindings estén disponibles a todas las
+     * llamadas de log async dentro de `fn`.
+     *
+     * @param bindings - Pares key-value a adjuntar durante la ejecución de `fn`
+     * @param fn - Función async a ejecutar con los bindings en scope
+     * @returns El valor de retorno de `fn`
+     *
+     * @example
+     * await logger.withContextAsync({ requestId: 'r-42' }, async () => {
+     *   await fetchData(); // los logs de aquí ven requestId en attributes
+     * });
+     *
+     * @see {@link child} para un child logger persistente
+     * @see {@link withContext} para la variante con callback sincrónico
+     */
+    withContextAsync<R>(bindings: Record<string, unknown>, fn: () => Promise<R>): Promise<R>;
+    /**
+     * Devuelve una copia inmutable de este logger con el contexto extra bound.
+     * Las llamadas futuras sobre el child emiten con el contexto mergueado,
+     * sin mutar al parent — el patrón canónico de MDC.
+     *
+     * @param extra - Pares key-value a adjuntar (requestId, userId, ...)
+     * @returns Un nuevo Logger con el contexto mergueado
+     *
+     * @example
+     * const reqLog = logger.child({ requestId: req.id });
+     * reqLog.info('start');     // emite attributes: { requestId }
+     * logger.info('unrelated'); // NO afectado — el contexto del parent queda intacto
+     *
+     */
+    child(extra: Record<string, unknown>): Logger;
+    /**
+     * Descarta todas las keys del contexto bound. Tras esta llamada, los
+     * records emitidos dejan de llevar `attributes` hasta que
+     * {@link withContext} o {@link child} restablezcan uno.
+     *
+     * @returns La misma instancia del logger, ahora sin contexto
+     */
+    clearContext(): this;
+    /**
+     * Snapshot del contexto bound. El objeto devuelto es una shallow copy:
+     * mutarlo NO afecta lo que emiten las llamadas de log posteriores.
+     *
+     * @returns Un snapshot read-only del contexto actual
+     */
+    getContext(): Readonly<Record<string, unknown>>;
+    /**
+     * Actualiza el resource OTel por defecto (service.name, version, env).
+     * Se persiste en el campo `resource` de cada record emitido, salvo que
+     * el propio record lo override.
+     *
+     * @param resource - Resource OTel parcial a merguear con el actual
+     * @returns La misma instancia del logger, para chaining
+     *
+     * @example
+     * logger.setResource({ 'service.name': 'api', 'service.version': '1.2.3' });
+     *
+     */
+    setResource(resource: Partial<ILogResourceRef>): this;
     /**
      * Reinicia el logger a la configuración por defecto
      *
@@ -151,19 +273,21 @@ export declare class Logger {
      * logger.resetConfig();
      * // Todo vuelve a la configuración inicial
      *
-     * @since 0.3.0
      */
     resetConfig(): void;
     /**
-     * Método de limpieza para eliminar listeners y liberar recursos
+     * Método de limpieza para eliminar listeners y liberar recursos.
+     *
+     * Vacía los transports (drain), limpia timers, suelta la lista de
+     * handlers legacy, resetea el group depth y limpia el context.
+     * Seguro de invocar múltiples veces.
      *
      * @example
      * // Antes de cerrar la aplicación
-     * logger.cleanup();
+     * await logger.cleanup();
      *
-     * @since 0.3.0
      */
-    cleanup(): void;
+    cleanup(): Promise<void>;
     /**
      * Aplica un preset inteligente - funciona perfectamente sin configuración
      *
@@ -176,9 +300,8 @@ export declare class Logger {
      * logger.preset('glassmorphism'); // Efectos de blur modernos
      * logger.preset('minimal');       // Minimalista y elegante
      * logger.preset('debug');         // Modo desarrollo detallado
-     * logger.preset('production');    // Optimizado para producción
+     * logger.preset('production');    // Enfocado en producción
      *
-     * @since 0.3.0
      */
     preset(name: string): void;
     /**
@@ -190,7 +313,6 @@ export declare class Logger {
      * const disponibles = logger.presets();
      * console.log(disponibles); // ['default', 'cyberpunk', 'glassmorphism', ...]
      *
-     * @since 0.3.0
      */
     presets(): string[];
     /**
@@ -200,9 +322,8 @@ export declare class Logger {
      * logger.hideTimestamp();
      * logger.info('Sin marca de tiempo'); // Sin timestamp visible
      *
-     * @since 0.3.0
      */
-    hideTimestamp(): void;
+    hideTimestamp(): this;
     /**
      * Muestra el timestamp en los logs
      *
@@ -210,9 +331,8 @@ export declare class Logger {
      * logger.showTimestamp();
      * logger.info('Con marca de tiempo'); // [2024-01-15 10:30:45] Con marca de tiempo
      *
-     * @since 0.3.0
      */
-    showTimestamp(): void;
+    showTimestamp(): this;
     /**
      * Oculta la información de ubicación (archivo:línea) en los logs
      *
@@ -220,9 +340,8 @@ export declare class Logger {
      * logger.hideLocation();
      * logger.debug('Sin ubicación'); // Sin mostrar archivo:línea
      *
-     * @since 0.3.0
      */
-    hideLocation(): void;
+    hideLocation(): this;
     /**
      * Muestra la información de ubicación (archivo:línea) en los logs
      *
@@ -230,9 +349,8 @@ export declare class Logger {
      * logger.showLocation();
      * logger.debug('Con ubicación'); // app.js:42 Con ubicación
      *
-     * @since 0.3.0
      */
-    showLocation(): void;
+    showLocation(): this;
     /**
      * Oculta los badges en los logs
      *
@@ -241,9 +359,8 @@ export declare class Logger {
      * const api = logger.api('REST');
      * api.info('Sin badges'); // Sin mostrar [API] [REST]
      *
-     * @since 0.3.0
      */
-    hideBadges(): void;
+    hideBadges(): this;
     /**
      * Muestra los badges en los logs
      *
@@ -252,62 +369,95 @@ export declare class Logger {
      * const api = logger.api('GraphQL');
      * api.info('Con badges'); // [API] [GraphQL] Con badges
      *
-     * @since 0.3.0
      */
-    showBadges(): void;
+    showBadges(): this;
     /**
-     * Crea un logger para componentes con estilo automático
+     * Establece múltiples badges para los logs
      *
-     * @param {string} name - Nombre del componente
-     * @returns {ComponentLogger} Logger con scope de componente
+     * @param {string[]} badges - Array de badges a mostrar
+     * @returns {this} Logger instance para encadenamiento
      *
      * @example
-     * const authLogger = logger.component('Autenticación');
-     * authLogger.info('Validando credenciales');
-     * // [COMPONENT] [Autenticación] Validando credenciales
+     * logger.badges(['v3', 'stable']).info('Release publicado');
+     * logger.badges(['API', 'v2']).warn('Endpoint deprecado');
+     *
+     */
+    badges(badges: string[]): this;
+    /**
+     * Añade un badge individual a la lista
+     *
+     * @param {string} badge - Badge a añadir
+     * @returns {this} Logger instance para encadenamiento
      *
-     * authLogger.success('Usuario autenticado');
-     * // [COMPONENT] [Autenticación] ✓ Usuario autenticado
+     * @example
+     * logger.badge('DEBUG').badge('AUTH').info('Token validado');
      *
-     * @since 0.3.0
      */
-    component(name: string): any;
+    badge(badge: string): this;
     /**
-     * Crea un logger para APIs con badges automáticos
+     * Limpia todos los badges activos
      *
-     * @param {string} name - Nombre de la API o endpoint
-     * @returns {APILogger} Logger con scope de API
+     * @returns {this} Logger instance para encadenamiento
      *
      * @example
-     * const api = logger.api('REST');
-     * api.info('GET /users');
-     * // [API] [REST] GET /users
+     * logger.clearBadges().info('Sin badges');
+     *
+     */
+    clearBadges(): this;
+    /**
+     * Crea un logger scoped para un componente o módulo del dominio.
      *
-     * // Con badges adicionales
-     * api.badges(['v2', 'cached']).info('Respuesta desde caché');
-     * // [API] [v2] [cached] [REST] Respuesta desde caché
+     * El `ComponentLogger` resultante prepends un badge `[name]` a cada
+     * mensaje y comparte configuración, transports y hooks con el logger
+     * padre. Útil para trazar el origen de los logs en apps con muchos
+     * módulos (Auth, DB, Cache, ...).
+     *
+     * @param {string} name - Nombre del componente que aparecerá como badge
+     * @returns {ComponentLogger} Logger scoped para el componente
+     *
+     * @example
+     * const auth = logger.component('Auth');
+     * auth.info('Validando token');   // [Auth] Validando token
+     * auth.success('Token válido');
      *
-     * @since 0.3.0
+     * @see {@link api} para loggers de endpoints REST/GraphQL
+     * @see {@link scope} para un scope genérico sin badge de componente
      */
-    api(name: string): any;
+    component(name: string): ComponentLogger;
     /**
-     * Crea un logger con scope general y soporte de badges
+     * Crea un logger scoped para un endpoint o surface de API.
      *
-     * @param {string} name - Nombre del scope
-     * @returns {ScopedLogger} Logger con scope personalizado
+     * Como `component()` pero con styling orientado a APIs (badge `[API]`
+     * por defecto más el nombre del sub-scope). Útil para distinguir
+     * tráfico REST vs GraphQL vs WebSocket en los logs.
+     *
+     * @param {string} name - Nombre de la API o surface (p.ej. `'REST'`, `'GraphQL'`)
+     * @returns {APILogger} Logger scoped para la API
      *
      * @example
-     * const dbLogger = logger.scope('Database');
-     * dbLogger.info('Conectando a MongoDB');
-     * // [Database] Conectando a MongoDB
+     * const rest = logger.api('REST');
+     * rest.info('GET /users/42');     // [API] [REST] GET /users/42
+     *
+     * @see {@link component} para loggers de componentes de dominio
+     */
+    api(name: string): APILogger;
+    /**
+     * Crea un logger scoped genérico con un prefijo.
      *
-     * // Con badges personalizados
-     * dbLogger.badge('SLOW').warn('Query tardó 5s');
-     * // [SLOW] [Database] Query tardó 5s
+     * Variante minimal de `component()` / `api()`: solo aplica un prefijo
+     * de scope sin badges ni styling especial. Útil para sub-módulos que
+     * no encajan en las categorías de `component`/`api`.
+     *
+     * @param {string} name - Texto del prefijo de scope
+     * @returns {ScopedLogger} Logger con el scope aplicado
+     *
+     * @example
+     * const db = logger.scope('db');
+     * db.info('Pool conectado');      // [db] Pool conectado
      *
-     * @since 0.3.0
+     * @see {@link component} y {@link api} para variantes con badges
      */
-    scope(name: string): any;
+    scope(name: string): ScopedLogger;
     /**
      * Personalización simple con configuración mínima
      *
@@ -326,7 +476,6 @@ export declare class Logger {
      *   spacing: 'compact'
      * });
      *
-     * @since 0.3.0
      */
     customize(overrides: {
         message?: {
@@ -352,10 +501,6 @@ export declare class Logger {
         };
         spacing?: 'compact' | 'normal' | 'spacious';
     }): void;
-    /**
-     * Access advanced styling API (for power users)
-     */
-    styles(): any;
     /**
      * Añade un handler personalizado para extender funcionalidad
      *
@@ -363,38 +508,216 @@ export declare class Logger {
      *
      * @example
      * // Handler personalizado para enviar logs a servidor
-     * const remoteHandler = new RemoteLogHandler('https://api.ejemplo.com/logs');
-     * logger.addHandler(remoteHandler);
+     * logger.addHandler({
+     *   handle(level, message, args, metadata) {
+     *     fetch('/logs', { method: 'POST', body: JSON.stringify({ level, message }) });
+     *   }
+     * });
      *
      * @example
-     * // Handler para guardar en archivo
-     * const fileHandler = new FileLogHandler('./app.log');
-     * logger.addHandler(fileHandler);
+     * // Para escribir a archivo, usa `addTransport` con un `FileTransport`
+     * logger.addTransport({ target: new FileTransport({ destination: 'app.log' }) });
      *
-     * @since 0.3.0
      */
     addHandler(handler: ILogHandler): void;
     /**
      * Obtiene todos los handlers registrados
      *
      * @returns {ILogHandler[]} Array de handlers activos
-     * @since 0.3.0
      */
     getHandlers(): ILogHandler[];
     /**
-     * Obtiene el handler de exportación si está disponible
+     * Añade un serializador personalizado para un tipo específico
+     *
+     * @param type - Constructor del tipo a serializar
+     * @param serializer - Función de serialización
+     * @param priority - Prioridad (mayor = primero)
+     *
+     * @example
+     * logger.addSerializer(Error, (err) => ({
+     *   name: err.name,
+     *   message: err.message,
+     *   stack: err.stack?.split('\n').slice(0, 5)
+     * }));
+     *
+     */
+    addSerializer<T>(type: new (...args: unknown[]) => T, serializer: SerializerFn<T>, priority?: number): void;
+    /**
+     * Elimina un serializador registrado
+     *
+     * @param type - Constructor del tipo a remover
+     * @returns true si se eliminó
+     *
+     */
+    removeSerializer<T>(type: new (...args: unknown[]) => T): boolean;
+    /**
+     * Obtiene el registry de serializadores
      *
-     * @returns {ExportLogHandler | undefined} Handler de exportación o undefined
-     * @since 0.3.0
+     * @returns SerializerRegistry
      */
-    getExportHandler(): ExportLogHandler | undefined;
+    getSerializerRegistry(): SerializerRegistry;
     /**
-     * Verifica si un nivel de log debe mostrarse según la verbosidad actual
+     * Registra un hook para un evento
+     *
+     * @param event - Evento: 'beforeLog' | 'afterLog' | 'onError'
+     * @param callback - Función a ejecutar
+     * @param priority - Prioridad (mayor = primero)
+     * @returns Función para desregistrar
+     *
+     * @example
+     * const unsubscribe = logger.on('beforeLog', (entry) => {
+     *   entry.correlationId = getCorrelationId();
+     *   return entry;
+     * });
+     *
+     */
+    on(event: HookEvent, callback: HookCallback, priority?: number): () => void;
+    /**
+     * Registra un hook que se ejecuta solo una vez
+     *
+     * @param event - Evento: 'beforeLog' | 'afterLog' | 'onError'
+     * @param callback - Función a ejecutar
+     * @param priority - Prioridad (mayor = primero)
+     * @returns Función para desregistrar
+     *
+     */
+    once(event: HookEvent, callback: HookCallback, priority?: number): () => void;
+    /**
+     * Elimina un hook registrado
+     *
+     * @param event - Evento del hook
+     * @param callback - Callback a remover
+     * @returns true si se eliminó
+     *
+     */
+    off(event: HookEvent, callback: HookCallback): boolean;
+    /**
+     * Añade un middleware al pipeline
+     *
+     * @param middleware - Función middleware
+     * @param priority - Prioridad (mayor = primero)
+     * @returns Función para desregistrar
+     *
+     * @example
+     * logger.use((entry, next) => {
+     *   entry.requestId = asyncLocalStorage.getStore()?.requestId;
+     *   next();
+     * });
+     *
+     */
+    use(middleware: MiddlewareFn, priority?: number): () => void;
+    /**
+     * Obtiene el HookManager
+     *
+     * @returns HookManager
+     */
+    getHookManager(): HookManager;
+    /**
+     * Añade un transport para envío de logs
+     *
+     * @param target - Configuración del transport
+     * @returns ID único del transport
+     *
+     * @example
+     * // File transport
+     * logger.addTransport({
+     *   target: 'file',
+     *   options: { destination: '/var/log/app.log' }
+     * });
+     *
+     * @example
+     * // HTTP transport con batching
+     * logger.addTransport({
+     *   target: 'http',
+     *   options: {
+     *     url: 'https://logs.example.com',
+     *     batchSize: 100,
+     *     flushInterval: 5000
+     *   },
+     *   level: 'warn'
+     * });
+     *
+     */
+    addTransport(target: TransportTarget): string;
+    /**
+     * Elimina un transport
+     *
+     * @param id - ID del transport a remover
+     * @returns true si se eliminó
+     *
+     */
+    removeTransport(id: string): boolean;
+    /**
+     * Fuerza el flush de todos los transports
+     *
+     * @returns Promise que resuelve cuando todos los buffers están vaciados
+     *
+     */
+    flushTransports(): Promise<void>;
+    /**
+     * Cierra todos los transports
+     *
+     * @returns Promise que resuelve cuando todos están cerrados
+     *
+     */
+    closeTransports(): Promise<void>;
+    /**
+     * Obtiene el TransportManager
+     *
+     * @returns TransportManager o undefined si no hay transports
+     */
+    getTransportManager(): TransportManager | undefined;
+    /**
+     * Verifica si un nivel de log debe mostrarse según la verbosidad actual.
      * @private
      * @param {LogLevel} level - Nivel de log a verificar
      * @returns {boolean} True si debe mostrarse, false si no
      */
     private shouldLog;
+    /**
+     * Tag pendiente de inyectar en el siguiente `TransportRecord` emitido
+     * por `log()`. Lo fijan `success()` y `logWithBindingsAndTag()` antes
+     * de delegar; `log()` lo consume y lo resetea a `undefined`.
+     *
+     * @internal
+     */
+    protected _dispatchTag: string | undefined;
+    /**
+     * Computa el contexto completamente mergueado para este logger.
+     *
+     * La cadena de contexto se construye en el momento de crear el child:
+     * cada child almacena el contexto fully-merged de su parent (en ese
+     * instante) como `_parentContextRecord`. Esto implica que
+     * `_parentContextRecord` ya contiene los bindings de todos los ancestros
+     * en el orden de precedencia correcto (root primero, child más cercano al final).
+     *
+     * Orden de merge (gana el último):
+     *   1. _parentContextRecord — snapshot del contexto mergueado del parent en la creación
+     *   2. _bindings            — bindings propios de este logger (llamadas a `child()`)
+     *   3. ALS store            — scope de `withContext`/`withContextAsync` (prioridad máxima)
+     *
+     * @internal
+     * @returns El record de contexto mergueado
+     */
+    private _getMergedContext;
+    /** @internal Expone el contexto base mergueado (sin ALS) a la closure de la child factory de LogContext. */
+    _captureMergedContext(): Record<string, unknown>;
+    /**
+     * Construye y despacha un `TransportRecord` al {@link TransportManager}
+     * (no-op si no hay transports registrados). Lo comparten todos los
+     * caminos de log — `log()`, `success()` y los métodos visuales como
+     * `table()` / `group()` / `time()` — para que toda emisión atraviese
+     * el mismo pipeline de transports.
+     *
+     * @protected
+     * @param {LogLevel} level - Nivel canónico (trace/debug/info/warn/error/critical)
+     * @param {string} message - Mensaje final, post-hook
+     * @param {string | undefined} prefix - Prefijo efectivo (global + scope)
+     * @param {StackInfo | null} stackInfo - Ubicación del caller, opcional
+     * @param {Partial<TransportRecord>} [extra] - Campos extra a mergear en el record
+     *        (p.ej. `{ tag: 'success' }` o `attributes` adicionales)
+     */
+    protected dispatchToTransports(level: LogLevel, message: string, prefix: string | undefined, stackInfo: StackInfo | null, extra?: Partial<TransportRecord>): void;
     /**
      * Obtiene el prefijo efectivo (global + scope)
      * @private
@@ -402,149 +725,174 @@ export declare class Logger {
      */
     private getEffectivePrefix;
     /**
-     * Método central de logging que maneja estilos y formato
+     * Método central de logging. Espera el hook pipeline `beforeLog`
+     * antes de despachar a consola y transports, para que redacciones
+     * o enriquecimientos (PII, correlation IDs) se reflejen en el
+     * mensaje emitido.
+     *
+     * Los callers fire-and-forget (p.ej. `logger.info(...)` sin `await`)
+     * siguen funcionando: el `Promise<void>` resultante se descarta.
+     * Se recomienda `await` cuando los hooks `beforeLog` mutan `message`.
+     *
+     * El tag opcional (`TransportRecord.tag`) NO se pasa como argumento:
+     * se establece vía `_dispatchTag` (ver `success()` y
+     * {@link logWithBindingsAndTag}) antes de invocar este método.
+     *
      * @protected
      * @param {LogLevel} level - Nivel del log
-     * @param {...any} args - Argumentos a loggear
+     * @param {unknown[]} args - Argumentos a loggear (mensaje + datos)
+     * @returns {Promise<void>} Promesa que resuelve al completar el dispatch
+     *
      */
-    protected log(level: LogLevel, ...args: any[]): void;
+    protected log(level: LogLevel, ...args: unknown[]): Promise<void>;
     /**
-     * Registra información de debug (prioridad más baja)
+     * Emite un log aplicando bindings (badges, scope) al prefijo del
+     * mensaje antes de delegar en {@link Logger.log}.
      *
-     * @param {...any} args - Mensajes y datos a loggear
+     * No es API pública de consumo: existe para que `ScopedLogger`
+     * (`component()` / `api()` / `scope()`) pueda reutilizar el pipeline
+     * central de `log()` sin duplicar la lógica de styling/badges.
      *
-     * @example
-     * logger.debug('Variable estado:', { usuario: 'Juan', activo: true });
-     * logger.debug('Iniciando proceso de validación');
+     * @internal
+     * @param {Bindings} bindings - Bindings de scope (badges, scope name, ...)
+     * @param {LogLevel} level - Nivel de log
+     * @param {unknown[]} args - Argumentos a loggear
+     * @returns {Promise<void>} Promesa del dispatch
      *
-     * @since 0.3.0
+     * @see {@link logWithBindingsAndTag} para la variante con `tag`
+     */
+    logWithBindings(bindings: Bindings, level: LogLevel, ...args: unknown[]): Promise<void>;
+    /**
+     * Como {@link logWithBindings} pero fija `_dispatchTag` antes de
+     * delegar, para que `log()` despache el `TransportRecord` con el
+     * tag indicado. Lo usa `ScopedLogger.success()` para propagar
+     * `tag: 'success'` a través del pipeline normal de `log()`.
+     *
+     * @internal
+     * @param {Bindings} bindings - Bindings de scope (badges, scope name, ...)
+     * @param {LogLevel} level - Nivel de log
+     * @param {LogTag} tag - Tag a inyectar en el `TransportRecord`
+     * @param {unknown[]} args - Argumentos a loggear
+     * @returns {Promise<void>} Promesa del dispatch
      */
-    debug(...args: any[]): void;
+    logWithBindingsAndTag(bindings: Bindings, level: LogLevel, tag: LogTag, ...args: unknown[]): Promise<void>;
     /**
-     * Registra mensajes informativos
+     * Registra mensajes de debug (nivel más verboso junto a `trace`).
+     * Pensado para diagnóstico de desarrollo: valores intermedios, flags
+     * de control flow, estado interno. Devuelve `Promise<void>`.
+     *
+     * Filtrado por defecto cuando `verbosity > 'debug'` (ver `setVerbosity`).
      *
-     * @param {...any} args - Mensajes y datos informativos
+     * @param {unknown[]} args - Mensaje + datos a inspeccionar
+     * @returns {Promise<void>} Promesa del dispatch
      *
      * @example
-     * logger.info('Servidor iniciado en puerto 3000');
-     * logger.info('Usuario conectado:', userId);
-     * logger.info('Procesando', totalItems, 'elementos');
+     * logger.debug('Estado interno:', { conn, queueSize });
+     * logger.debug('Entrando en branch X');
      *
-     * @since 0.3.0
+     * @see {@link trace} para diagnósticos aún más granulares
+     * @see {@link setVerbosity} para controlar el nivel mínimo visible
      */
-    info(...args: any[]): void;
+    debug(...args: unknown[]): Promise<void>;
     /**
-     * Registra mensajes de advertencia
+     * Registra mensajes informativos. El `await` retorna cuando el hook
+     * `beforeLog` y el dispatch a transports han terminado.
      *
-     * @param {...any} args - Mensajes de advertencia
+     * @param args - Mensajes y datos informativos
      *
      * @example
-     * logger.warn('Memoria al 85% de capacidad');
-     * logger.warn('API deprecada, usar v2');
-     * logger.warn('Reintentos agotados:', maxRetries);
+     * logger.info('Servidor iniciado en puerto 3000');
+     * await logger.info('Procesando', totalItems, 'elementos'); // espera hooks
      *
-     * @since 0.3.0
      */
-    warn(...args: any[]): void;
+    info(...args: unknown[]): Promise<void>;
     /**
-     * Registra mensajes de error
+     * Registra mensajes de advertencia.
      *
-     * @param {...any} args - Mensajes de error y stack traces
+     * @param args - Mensajes de advertencia
      *
-     * @example
-     * logger.error('Fallo en conexión a base de datos');
-     * logger.error('Error al procesar:', error.message, error.stack);
-     * logger.error('Código de error:', errorCode);
+     */
+    warn(...args: unknown[]): Promise<void>;
+    /**
+     * Registra mensajes de error.
+     *
+     * @param args - Mensaje de error y stack traces
      *
-     * @since 0.3.0
      */
-    error(...args: any[]): void;
+    error(...args: unknown[]): Promise<void>;
     /**
-     * Registra mensajes de éxito (nivel info especial)
+     * Registra mensajes de éxito. Mapeado internamente a nivel `info` con
+     * styling de success y `record.tag = 'success'` para que los transports
+     * puedan distinguirlo (sin perder info semantics para filtering).
      *
-     * @param {...any} args - Mensajes de operaciones exitosas
+     * @param args - Mensaje + datos adicionales
      *
      * @example
      * logger.success('Base de datos conectada');
      * logger.success('Usuario creado con ID:', userId);
      * logger.success('✓ Tests pasados: 42/42');
      *
-     * @since 0.3.0
      */
-    success(...args: any[]): void;
+    success(...args: unknown[]): Promise<void>;
     /**
-     * Registra información de trace (debugging detallado)
+     * Registra información de trace (nivel más bajo, debajo de debug).
+     * Alineado con OpenTelemetry `TRACE` severity (1-4).
      *
-     * @param {...any} args - Datos detallados para debugging
+     * @param args - Datos muy verbosos (entrada/salida de funciones, valores intermedios)
      *
      * @example
      * logger.trace('Entrando en función processData');
-     * logger.trace('Stack completo:', new Error().stack);
+     * logger.trace('Variables intermedias:', { a, b, c });
      *
-     * @since 0.3.0
      */
-    trace(...args: any[]): void;
+    trace(...args: unknown[]): void;
     /**
-     * Registra errores críticos (prioridad más alta)
+     * Registra errores críticos (prioridad más alta).
      *
-     * @param {...any} args - Errores críticos del sistema
+     * @param args - Errores críticos del sistema
      *
      * @example
-     * logger.critical('Sistema caído - reinicio inmediato requerido');
-     * logger.critical('Pérdida de datos detectada');
-     * logger.critical('Brecha de seguridad:', securityError);
+     * await logger.critical('Sistema caído - reinicio inmediato requerido');
      *
-     * @since 0.3.0
      */
-    critical(...args: any[]): void;
+    critical(...args: unknown[]): Promise<void>;
     /**
-     * Muestra datos en formato de tabla
+     * Muestra datos en formato de tabla. Pasa por la pipeline completa
+     * (outputMode-respecting writeOutput + transports + hooks).
      *
-     * @param {any} data - Datos a mostrar (array de objetos o matriz)
-     * @param {string[]} columns - Columnas específicas a mostrar (opcional)
+     * @param data - Array de objetos o matriz
+     * @param columns - Columnas específicas a mostrar (opcional)
      *
      * @example
-     * const usuarios = [
-     *   { id: 1, nombre: 'Juan', edad: 30 },
-     *   { id: 2, nombre: 'María', edad: 25 }
-     * ];
-     * logger.table(usuarios);
-     * logger.table(usuarios, ['nombre', 'edad']); // Solo estas columnas
+     * logger.table([{ id: 1, nombre: 'Juan' }, { id: 2, nombre: 'María' }]);
      *
-     * @since 0.3.0
      */
-    table(data: any, columns?: string[]): void;
+    table(data: unknown, columns?: string[]): void;
     /**
-     * Inicia un grupo colapsable en la consola
+     * Inicia un grupo colapsable en la consola. Emite un marker a
+     * transports con `attributes.logger.visual = 'groupStart'` para que
+     * backends puedan reconstruir la jerarquía.
      *
-     * @param {string} label - Etiqueta del grupo
-     * @param {boolean} collapsed - Si el grupo inicia colapsado (default: false)
+     * @param label - Etiqueta del grupo
+     * @param collapsed - Si el grupo inicia colapsado (default: false)
      *
      * @example
      * logger.group('Procesando usuarios');
      * logger.info('Usuario 1 procesado');
-     * logger.info('Usuario 2 procesado');
-     * logger.groupEnd();
-     *
-     * @example
-     * // Grupo colapsado por defecto
-     * logger.group('Detalles adicionales', true);
-     * logger.debug('Información detallada aquí');
      * logger.groupEnd();
      *
-     * @since 0.3.0
      */
     group(label: string, collapsed?: boolean): void;
     /**
-     * Finaliza el grupo actual de la consola
+     * Finaliza el grupo actual de la consola. Emite un marker a transports
+     * simétrico al `group()` start, para que backends puedan cerrar la
+     * jerarquía correctamente.
      *
      * @example
      * logger.group('Operaciones');
      * logger.info('Operación 1');
-     * logger.info('Operación 2');
-     * logger.groupEnd(); // Cierra el grupo
+     * logger.groupEnd();
      *
-     * @since 0.3.0
      */
     groupEnd(): void;
     /**
@@ -557,22 +905,21 @@ export declare class Logger {
      * // ... operación costosa ...
      * logger.timeEnd('proceso-datos'); // ⏱️ Timer ended: proceso-datos - 1523.45ms
      *
-     * @since 0.3.0
      */
     time(label: string): void;
     /**
      * Finaliza un temporizador y muestra el tiempo transcurrido
      *
      * @param {string} label - Etiqueta del temporizador a finalizar
+     * @returns {number} Milisegundos transcurridos, o `-1` si no se encuentra el timer
      *
      * @example
      * logger.time('consulta-db');
      * await consultarBaseDatos();
-     * logger.timeEnd('consulta-db'); // ⏱️ Timer ended: consulta-db - 234.56ms
+     * const elapsed = logger.timeEnd('consulta-db'); // ⏱️ Timer ended: consulta-db - 234.56ms
      *
-     * @since 0.3.0
      */
-    timeEnd(label: string): void;
+    timeEnd(label: string): number;
     /**
      * Muestra un banner con el tipo especificado o configurado
      *
@@ -584,7 +931,6 @@ export declare class Logger {
      * logger.showBanner('svg');      // Banner con gráfico SVG
      * logger.showBanner();           // Usa el tipo configurado
      *
-     * @since 0.3.0
      */
     showBanner(bannerType?: BannerType): void;
     /**
@@ -603,7 +949,6 @@ export declare class Logger {
      * const customSVG = '<svg>...</svg>';
      * logger.logWithSVG('Logo', customSVG, { width: 400, height: 100 });
      *
-     * @since 0.3.0
      */
     logWithSVG(message: string, svgContent?: string, options?: StyleOptions): void;
     /**
@@ -616,26 +961,117 @@ export declare class Logger {
      * logger.logAnimated('🌈 Animación en progreso');
      * logger.logAnimated('Cargando...', 5); // Animación de 5 segundos
      *
-     * @since 0.3.0
      */
     logAnimated(message: string, duration?: number): void;
     /**
-     * Agrupa logs por una propiedad específica usando Object.groupBy (cuando esté disponible)
+     * Muestra un indicador de progreso de pasos en la terminal
+     *
+     * @param {number} current - Número de paso actual
+     * @param {number} total - Número total de pasos
+     * @param {string} message - Descripción del paso
+     *
+     * @example
+     * logger.step(1, 5, 'Analyzing repository...');
+     * logger.step(2, 5, 'Generating commit message...');
+     *
+     */
+    step(current: number, total: number, message: string): void;
+    /**
+     * Muestra un header con estilo y subtítulo opcional
+     *
+     * @param {string} title - Texto del título principal
+     * @param {string} subtitle - Subtítulo opcional (se renderiza atenuado)
+     *
+     * @example
+     * logger.header('Commit Wizard', 'v2.0.0');
+     *
+     */
+    header(title: string, subtitle?: string): void;
+    /**
+     * Muestra una línea divisoria horizontal
+     *
+     * @example
+     * logger.divider();
+     *
+     */
+    divider(): void;
+    /**
+     * Emite una línea en blanco
+     *
+     * @example
+     * logger.blank();
+     *
+     */
+    blank(): void;
+    /**
+     * Renderiza contenido dentro de un box con borde
+     *
+     * @param {string} content - String de contenido (puede contener newlines)
+     * @param {IBoxOptions} options - Opciones de renderizado del box
+     *
+     * @example
+     * logger.box('3 commits generated\nProvider: Groq', { title: 'Done', borderColor: '#00ff00' });
+     *
+     */
+    box(content: string, options?: IBoxOptions): void;
+    /**
+     * Renderiza un array de objetos como una tabla ASCII formateada.
+     * Distinto del método `table()` existente, que usa `console.table`.
+     *
+     * @param {Record<string, unknown>[]} rows - Array de objetos fila
+     * @param {ITableOptions} options - Opciones de renderizado de la tabla
+     *
+     * @example
+     * logger.cliTable([
+     *   { provider: 'Groq', status: 'Available', model: 'llama-3.3-70b' },
+     *   { provider: 'Gemini', status: 'Configured', model: 'gemini-2.5-flash' },
+     * ]);
+     *
+     */
+    cliTable(rows: Record<string, unknown>[], options?: ITableOptions): void;
+    /**
+     * Crea un handle de spinner para mostrar progreso durante operaciones async.
+     * Devuelve un `NoopSpinner` en entornos non-TTY.
+     *
+     * @param {string} message - Texto inicial del spinner
+     * @returns {ISpinnerHandle} Controller del spinner
+     *
+     * @example
+     * const s = logger.spinner('Analyzing repository...');
+     * s.start();
+     * await analyzeRepo();
+     * s.succeed('Analysis complete (1.2s)');
+     *
+     */
+    spinner(message: string): ISpinnerHandle;
+    /**
+     * Fija el nivel de verbosidad del CLI, controlando a la vez la verbosidad
+     * de logs y la visibilidad de las primitives
      *
-     * @param {T[]} items - Array de elementos a agrupar
-     * @param {Function} groupBy - Función que retorna la clave de agrupación
+     * @param {CLILogLevel} level - Nivel de log del CLI
      *
      * @example
-     * const ventas = [
-     *   { producto: 'Laptop', categoria: 'Electrónica', precio: 1200 },
-     *   { producto: 'Mouse', categoria: 'Electrónica', precio: 25 },
-     *   { producto: 'Libro', categoria: 'Literatura', precio: 15 }
-     * ];
-     * logger.logGrouped(ventas, item => item.categoria);
+     * logger.setCLILevel('quiet');   // Solo errors, sin CLI primitives
+     * logger.setCLILevel('verbose'); // Debug logs + todas las CLI primitives
      *
-     * @since 0.3.0
      */
-    logGrouped<T>(items: T[], groupBy: (item: T) => string): void;
+    setCLILevel(level: CLILogLevel): void;
+    /**
+     * Devuelve el nivel de log del CLI actual
+     * @returns {CLILogLevel} Nivel de log del CLI actual
+     */
+    get cliLevel(): CLILogLevel;
+    /**
+     * Escribe output formateado al destino configurado.
+     * Respeta la configuración `outputMode` para output a consola, silencioso o custom.
+     *
+     * @private
+     * @param {string} message - Mensaje de log formateado
+     * @param {LogLevel} level - Nivel de log
+     * @param {string[]} styles - Estilos CSS para la consola del navegador
+     * @param {unknown[]} additionalArgs - Argumentos adicionales a loggear
+     */
+    private writeOutput;
     /**
      * Procesador de comandos CLI para configuración y exportación del logger
      *
@@ -653,33 +1089,43 @@ export declare class Logger {
      * await logger.cli('status');           // Muestra estado del logger
      * await logger.cli('help');             // Muestra ayuda de comandos
      *
-     * @since 0.3.0
      */
     cli(command: string): Promise<void>;
 }
 /**
- * Instancia singleton del logger con configuración por defecto
- * @constant {Logger}
+ * Resetea el singleton por defecto. Limpia la instancia cacheada para que la
+ * próxima llamada a `getDefaultLogger()` la reconstruya desde defaults. Útil
+ * para tests y escenarios de hot reload.
+ *
+ */
+export declare function resetDefaultLogger(): void;
+/**
+ * Lazy default export — every property access defers to `getDefaultLogger()`.
+ * Sin side-effects al importar el módulo (la primera llamada al singleton
+ * se produce en el primer acceso a una propiedad, no en el `import`).
+ *
+ * @example
+ * import logger from 'better-logger';
+ * logger.info('hello'); // first call here triggers singleton init
  */
-declare const defaultLogger: Logger;
-export default defaultLogger;
+declare const loggerProxy: Logger;
+export default loggerProxy;
 /**
  * Métodos individuales exportados para conveniencia
- * @description Todos los métodos están correctamente enlazados al singleton
- * @since 0.3.0
+ * @description Todos los métodos están correctamente enlazados al singleton lazy
  */
-export declare const debug: (...args: any[]) => void;
-export declare const info: (...args: any[]) => void;
-export declare const warn: (...args: any[]) => void;
-export declare const error: (...args: any[]) => void;
-export declare const success: (...args: any[]) => void;
-export declare const trace: (...args: any[]) => void;
-export declare const critical: (...args: any[]) => void;
-export declare const table: (data: any, columns?: string[]) => void;
+export declare const debug: (...args: unknown[]) => Promise<void>;
+export declare const info: (...args: unknown[]) => Promise<void>;
+export declare const warn: (...args: unknown[]) => Promise<void>;
+export declare const error: (...args: unknown[]) => Promise<void>;
+export declare const success: (...args: unknown[]) => Promise<void>;
+export declare const trace: (...args: unknown[]) => void;
+export declare const critical: (...args: unknown[]) => Promise<void>;
+export declare const table: (data: unknown, columns?: string[]) => void;
 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) => void;
+export declare const timeEnd: (label: string) => number;
 export declare const setGlobalPrefix: (prefix: string) => void;
 export declare const setVerbosity: (level: Verbosity) => void;
 export declare const addHandler: (handler: ILogHandler) => void;
@@ -689,20 +1135,34 @@ export declare const showBanner: (bannerType?: BannerType) => void;
 export declare const logWithSVG: (message: string, svgContent?: string, options?: StyleOptions) => void;
 export declare const logAnimated: (message: string, duration?: number) => void;
 export declare const cli: (command: string) => Promise<void>;
-export declare const cleanup: () => void;
+export declare const cleanup: () => Promise<void>;
 export declare const preset: (name: string) => void;
 export declare const presets: () => string[];
-export declare const hideTimestamp: () => void;
-export declare const showTimestamp: () => void;
-export declare const hideLocation: () => void;
-export declare const showLocation: () => void;
-export declare const hideBadges: () => void;
-export declare const showBadges: () => void;
-export declare const component: (name: string) => any;
-export declare const api: (name: string) => any;
-export declare const scope: (name: string) => any;
-export declare const customize: (overrides: any) => void;
-export declare const styles: () => any;
-export { FileLogHandler, RemoteLogHandler, AnalyticsLogHandler, ExportLogHandler } from './handlers/index.js';
+export declare const hideTimestamp: () => Logger;
+export declare const showTimestamp: () => Logger;
+export declare const hideLocation: () => Logger;
+export declare const showLocation: () => Logger;
+export declare const hideBadges: () => Logger;
+export declare const showBadges: () => Logger;
+export declare const badges: (badgeList: string[]) => Logger;
+export declare const badge: (badgeName: string) => Logger;
+export declare const clearBadges: () => Logger;
+export declare const component: (name: string) => ComponentLogger;
+export declare const api: (name: string) => APILogger;
+export declare const scope: (name: string) => ScopedLogger;
+export declare const customize: (overrides: Parameters<Logger["customize"]>[0]) => void;
+export declare const addSerializer: <T>(type: new (...args: unknown[]) => T, serializer: SerializerFn<T>, priority?: number) => void;
+export declare const removeSerializer: <T>(type: new (...args: unknown[]) => T) => boolean;
+export declare const on: (event: HookEvent, callback: HookCallback, priority?: number) => () => void;
+export declare const once: (event: HookEvent, callback: HookCallback, priority?: number) => () => void;
+export declare const off: (event: HookEvent, callback: HookCallback) => boolean;
+export declare const use: (middleware: MiddlewareFn, priority?: number) => () => void;
+export declare const addTransport: (target: TransportTarget) => string;
+export declare const removeTransport: (id: string) => boolean;
+export declare const flushTransports: () => Promise<void>;
+export declare const closeTransports: () => Promise<void>;
 export { StyleBuilder, StylePresets as Styles } from './styling/index.js';
+export { SerializerRegistry } from './serializers/index.js';
+export { HookManager } from './hooks/index.js';
+export { TransportManager, ConsoleTransport, FileTransport, HttpTransport } from './transports/index.js';
 //# sourceMappingURL=Logger.d.ts.map