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

package/dist/ScopedLogger.d.ts

@@ -1,318 +1,577 @@
-/**
- * @fileoverview ScopedLogger con badges y logging contextual
- * @version 0.3.0
- * @since 2024
- *
- * Proporciona loggers especializados con contexto, badges automáticos
- * y características avanzadas para componentes y APIs.
- */
 import { Logger } from './Logger.js';
-import type { LoggerConfig, LogLevel } from './types/index.js';
+import type { ISpinnerHandle, IBoxOptions, ITableOptions, CLILogLevel } from './types/index.js';
 /**
- * Logger con scope mejorado con badges y API simplificada
+ * Logger prefijado por un scope nominal. Mantiene su propio stack de badges
+ * y contextos y delega el envío de mensajes al {@link Logger} padre a través
+ * de bindings (`{ scope, badges }`).
+ *
+ * Es la base de la jerarquía temática: {@link APILogger} y
+ * {@link ComponentLogger} extienden de ella, y {@link ContextLogger} la
+ * consume para apilar/subdesapilar sub-prefijos en el scope.
  *
- * @class ScopedLogger
- * @extends Logger
- * @description Logger contextual que añade prefijos y badges automáticamente
+ * No se construye directamente: se obtiene con `logger.scope('name')`.
  *
  * @example
- * const dbLogger = logger.scope('Database');
- * dbLogger.info('Conectando...'); // [Database] Conectando...
+ * // El factory method del Logger raíz devuelve un ScopedLogger
+ * import logger from '@mks2508/better-logger';
  *
- * // Con badges personalizados
- * dbLogger.badge('SLOW').warn('Query lenta detectada');
- * // [SLOW] [Database] Query lenta detectada
+ * const http = logger.scope('HTTP');
+ * http.badge('OUTBOUND').info('Request enviada');
+ * // salida: [HTTP] [OUTBOUND] Request enviada
  *
- * @since 0.3.0
+ * @example
+ * // Anidar contextos dentro de un scope (el prefijo se compone con ':')
+ * const retry = http.context('retry');
+ * retry.run(() => http.warn('Reintentando petición'));
+ * // salida: [HTTP:retry] Reintentando petición
+ *
+ * @see {@link Logger.scope}
+ * @see {@link APILogger}
+ * @see {@link ComponentLogger}
+ * @see {@link ContextLogger}
  */
-export declare class ScopedLogger extends Logger {
-    private parentLogger;
-    private scopeName;
+export declare class ScopedLogger {
+    private readonly parent;
+    private readonly scopeName;
     private badgeList;
     private contextStack;
-    constructor(parentLogger: Logger, scopeName: string, config?: Partial<LoggerConfig>);
+    private _timers?;
+    /**
+     * Construye un ScopedLogger vinculado a un {@link Logger} padre.
+     *
+     * Los clientes no deben llamar a este constructor directamente: usen
+     * `logger.scope(name)`, que configura correctamente la instancia.
+     *
+     * @param {Logger} parent - Logger raíz al que se delegan los mensajes.
+     * @param {string} scopeName - Etiqueta del scope; se renderiza como
+     *   prefijo `[scopeName]` en cada línea.
+     */
+    constructor(parent: Logger, scopeName: string);
+    private get timers();
+    private getBindings;
+    private getScopePrefix;
     /**
-     * Añade múltiples badges a este logger con scope
+     * Reemplaza la lista actual de badges por la pasada y la aplica a todos
+     * los mensajes posteriores de este scope.
      *
-     * @param {string[]} badges - Array de badges a añadir
-     * @returns {ScopedLogger} Esta instancia para encadenamiento
+     * @param {string[]} badges - Etiquetas a mostrar como badges adyacentes
+     *   al prefijo (p. ej. `['OUTBOUND', 'CACHED']`).
+     * @returns {this} La misma instancia, para encadenar llamadas.
      *
      * @example
-     * const api = logger.scope('API');
-     * api.badges(['v2', 'beta', 'cached'])
-     *    .info('Respuesta desde caché');
-     * // [v2] [beta] [cached] [API] Respuesta desde caché
+     * logger.scope('HTTP').badges(['OUTBOUND', 'CACHED']).info('Cache hit');
+     * // salida: [HTTP] [OUTBOUND] [CACHED] Cache hit
      *
-     * @since 0.3.0
+     * @see {@link badge} para añadir sin reemplazar los existentes.
+     * @see {@link clearBadges} para vaciar la lista.
      */
-    badges(badges: string[]): ScopedLogger;
+    badges(badges: string[]): this;
     /**
-     * Añade un badge individual
+     * Añade un badge al scope de forma idempotente (no lo duplica si ya existe).
      *
-     * @param {string} badge - Badge a añadir
-     * @returns {ScopedLogger} Esta instancia para encadenamiento
+     * @param {string} badge - Etiqueta a añadir a la lista de badges.
+     * @returns {this} La misma instancia, para encadenar llamadas.
      *
      * @example
-     * dbLogger.badge('SLOW').warn('Query tardó 3s');
-     * // [SLOW] [Database] Query tardó 3s
+     * logger.scope('API')
+     *   .badge('OUTBOUND')
+     *   .badge('RETRY')
+     *   .warn('Reintentando');
+     * // salida: [API] [OUTBOUND] [RETRY] Reintentando
+     */
+    badge(badge: string): this;
+    /**
+     * Vacía la lista de badges del scope.
      *
-     * @since 0.3.0
+     * @returns {this} La misma instancia, para encadenar llamadas.
+     *
+     * @example
+     * const http = logger.scope('HTTP');
+     * http.badge('OUTBOUND').info('uno');
+     * http.clearBadges().info('dos');
+     * // [HTTP] [OUTBOUND] uno   /   [HTTP] dos
      */
-    badge(badge: string): ScopedLogger;
+    clearBadges(): this;
     /**
-     * Elimina todos los badges
+     * Aplica un theme preset al logger padre. El preset afecta a toda la
+     * instancia raíz (no solo a este scope) porque el style es compartido.
      *
-     * @returns {ScopedLogger} Esta instancia para encadenamiento
+     * @param {string} presetName - Nombre del preset registrado en el StyleManager.
+     * @returns {this} La misma instancia, para encadenar llamadas.
      *
      * @example
-     * api.clearBadges().info('Sin badges');
-     * // [API] Sin badges
+     * logger.scope('UI').style('cyberpunk').info('neon');
+     * @see {@link Logger.setTheme}
+     */
+    style(presetName: string): this;
+    /**
+     * Crea un {@link ContextLogger} vinculado a este scope. Los contextos se
+     * apilan en el prefijo separados por `:`, permitiendo agrupar bloques de
+     * logs relacionados (reintentos, sub-etapas, etc.) sin `console.group`.
      *
-     * @since 0.3.0
+     * @param {string} contextName - Nombre del contexto a apilar.
+     * @returns {ContextLogger} Handler con `run`, `runAsync`, `start`/`end`.
+     *
+     * @example
+     * const retry = logger.scope('HTTP').context('retry');
+     * retry.run(() => logger.warn('Reintentando'));
+     * // salida: [HTTP:retry] Reintentando
+     * @see {@link ContextLogger}
      */
-    clearBadges(): ScopedLogger;
+    context(contextName: string): ContextLogger;
     /**
-     * Establece un preset de estilo para este logger con scope
+     * Inicia un timer etiquetado bajo el namespace `<scopeName>:<label>`.
+     * El label es local a este scope, así que dos scopes pueden reutilizar el
+     * mismo nombre sin colisión.
      *
-     * @param {string} presetName - Nombre del preset a aplicar
-     * @returns {ScopedLogger} Esta instancia para encadenamiento
+     * @param {string} label - Identificador del timer.
      *
      * @example
-     * const errorLogger = logger.scope('ErrorHandler')
-     *   .style('cyberpunk');
+     * const http = logger.scope('HTTP');
+     * http.time('request');
+     * // ... trabajo ...
+     * http.timeEnd('request'); // imprime "Timer: request - 12.34ms"
+     * @see {@link timeEnd}
+     */
+    time(label: string): void;
+    /**
+     * Detiene un timer previamente iniciado con {@link time} y registra la
+     * duración con nivel `success`. Si el label no existe, emite un `warn`
+     * y devuelve `undefined`.
+     *
+     * @param {string} label - Mismo label pasado a {@link time}.
+     * @returns {number | undefined} Milisegundos transcurridos, o `undefined`
+     *   si el timer no estaba registrado.
      *
-     * @since 0.3.0
+     * @example
+     * const http = logger.scope('HTTP');
+     * http.time('fetch');
+     * await fetch(url);
+     * const ms = http.timeEnd('fetch');
+     * if (ms && ms > 1000) http.warn('Latencia alta');
      */
-    style(presetName: string): ScopedLogger;
+    timeEnd(label: string): number | undefined;
     /**
-     * Crea un contexto temporal que se limpia automáticamente
+     * Emite un mensaje a nivel `debug` con los bindings actuales del scope.
      *
-     * @param {string} contextName - Nombre del contexto
-     * @returns {ContextLogger} Logger con contexto temporal
+     * @param {...unknown[]} args - Mensaje y argumentos adicionales (objetos,
+     *   errores, etc.) serializados igual que en el logger raíz.
      *
      * @example
-     * const db = logger.scope('Database');
+     * logger.scope('DB').debug('query', { sql, params });
+     */
+    debug(...args: unknown[]): void;
+    /**
+     * Emite un mensaje a nivel `info` con los bindings actuales del scope.
      *
-     * // Contexto temporal para una operación
-     * db.context('Migration').run(() => {
-     *   db.info('Iniciando migración');
-     *   db.success('Tablas creadas');
-     * });
-     * // Contexto automáticamente limpiado
+     * @param {...unknown[]} args - Mensaje y argumentos adicionales.
      *
-     * @since 0.3.0
+     * @example
+     * logger.scope('AUTH').info('Login exitoso', { userId });
      */
-    context(contextName: string): ContextLogger;
+    info(...args: unknown[]): void;
+    /**
+     * Emite un mensaje a nivel `warn` con los bindings actuales del scope.
+     *
+     * @param {...unknown[]} args - Mensaje y argumentos adicionales.
+     *
+     * @example
+     * logger.scope('CACHE').warn('Cache miss', { key });
+     */
+    warn(...args: unknown[]): void;
     /**
-     * Sobrescribe el logging principal para incluir badges
-     * @protected
-     * @param {LogLevel} level - Nivel del log
-     * @param {...any} args - Argumentos del log
+     * Emite un mensaje a nivel `error` con los bindings actuales del scope.
+     *
+     * @param {...unknown[]} args - Mensaje y argumentos adicionales (típicamente
+     *   un `Error` o contexto del fallo).
+     *
+     * @example
+     * logger.scope('DB').error('Conexión rechazada', err);
      */
-    protected log(level: LogLevel, ...args: any[]): void;
+    error(...args: unknown[]): void;
     /**
-     * Obtiene la cadena de badges formateada
-     * @private
-     * @returns {string} Badges formateados como [BADGE1][BADGE2]
+     * Emite un mensaje con badge visual `SUCCESS` a nivel `info`. Úselo para
+     * hitos positivos dentro del scope (conexión establecida, sync completo,
+     * commit aplicado).
+     *
+     * @param {...unknown[]} args - Mensaje y argumentos adicionales.
+     *
+     * @example
+     * logger.scope('SYNC').success('Sincronización completa', { count: 42 });
      */
-    private getBadgeString;
+    success(...args: unknown[]): void;
     /**
-     * Obtiene el prefijo del scope (incluye stack de contexto)
-     * @private
-     * @returns {string} Prefijo completo con contextos
+     * Emite un mensaje a nivel `critical` con los bindings actuales del scope.
+     * Reservado para fallos que detienen el flujo de la aplicación.
+     *
+     * @param {...unknown[]} args - Mensaje y argumentos adicionales.
+     *
+     * @example
+     * logger.scope('PAY').critical('Pasarela inaccesible', err);
      */
-    private getScopePrefix;
+    critical(...args: unknown[]): void;
+    /**
+     * Emite un mensaje a nivel `trace` (verbosidad máxima) con los bindings
+     * actuales del scope. Solo aparece si la verbosity global lo permite.
+     *
+     * @param {...unknown[]} args - Mensaje y argumentos adicionales.
+     *
+     * @example
+     * logger.scope('NET').trace('packet', { bytes });
+     */
+    trace(...args: unknown[]): void;
+    /**
+     * Delegación a {@link Logger.step}: dibuja una barra de progreso discreta
+     * `current/total` para este scope.
+     *
+     * @param {number} current - Paso actual (1-indexed).
+     * @param {number} total - Total de pasos.
+     * @param {string} message - Texto mostrado junto al contador.
+     * @see {@link Logger.step}
+     */
+    step(current: number, total: number, message: string): void;
+    /**
+     * Delegación a {@link Logger.header}: imprime un título con separadores visuales.
+     *
+     * @param {string} title - Texto del título.
+     * @param {string} [subtitle] - Subtítulo opcional bajo el título.
+     * @see {@link Logger.header}
+     */
+    header(title: string, subtitle?: string): void;
     /**
-     * Método interno para añadir contexto
+     * Delegación a {@link Logger.divider}: imprime una línea separadora horizontal.
+     * @see {@link Logger.divider}
+     */
+    divider(): void;
+    /**
+     * Delegación a {@link Logger.blank}: inserta una línea en blanco.
+     * @see {@link Logger.blank}
+     */
+    blank(): void;
+    /**
+     * Delegación a {@link Logger.box}: dibuja un recuadro ANSI alrededor de `content`.
+     *
+     * @param {string} content - Texto a enmarcar.
+     * @param {IBoxOptions} [options] - Opciones de estilo del box.
+     * @see {@link Logger.box}
+     */
+    box(content: string, options?: IBoxOptions): void;
+    /**
+     * Delegación a {@link Logger.cliTable}: renderiza `rows` como tabla ASCII.
+     *
+     * @param {Record<string, unknown>[]} rows - Filas a mostrar.
+     * @param {ITableOptions} [options] - Opciones de columnas y estilo.
+     * @see {@link Logger.cliTable}
+     */
+    cliTable(rows: Record<string, unknown>[], options?: ITableOptions): void;
+    /**
+     * Delegación a {@link Logger.spinner}: arranca un spinner con `message`.
+     *
+     * @param {string} message - Texto a mostrar al lado del spinner.
+     * @returns {ISpinnerHandle} Handle para detener/actualizar el spinner.
+     * @see {@link Logger.spinner}
+     */
+    spinner(message: string): ISpinnerHandle;
+    /**
+     * Delegación a {@link Logger.setCLILevel}: ajusta el nivel mínimo de las
+     * primitivas CLI visibles.
+     *
+     * @param {CLILogLevel} level - Nivel CLI (`silent` … `verbose`).
+     * @see {@link Logger.setCLILevel}
+     */
+    setCLILevel(level: CLILogLevel): void;
+    /**
+     * Apila un contexto en el prefijo del scope. Invocado por
+     * {@link ContextLogger}; los clientes no deben llamarlo directamente.
+     *
+     * @param {string} context - Nombre del contexto a apilar.
      * @internal
      */
     _pushContext(context: string): void;
     /**
-     * Método interno para eliminar contexto
+     * Desapila el último contexto del prefijo del scope. Invocado por
+     * {@link ContextLogger}; los clientes no deben llamarlo directamente.
+     *
      * @internal
      */
     _popContext(): void;
 }
 /**
- * Logger específico para APIs con badges comunes de API
+ * Logger especializado para llamadas a APIs y servicios externos.
  *
- * @class APILogger
- * @extends ScopedLogger
- * @description Logger especializado para endpoints y servicios API
+ * Extiende {@link ScopedLogger} pre-seteando el badge `API` y exponiendo
+ * atajos para eventos típicos de integración: llamadas lentas ({@link slow}),
+ * rate limiting ({@link rateLimit}), fallos de autenticación ({@link auth}) y
+ * APIs deprecadas ({@link deprecated}).
+ *
+ * Se obtiene con `logger.api(name)` y no se construye directamente.
  *
  * @example
- * const api = logger.api('REST');
- * api.info('GET /users');
- * // [API] [REST] GET /users
+ * import logger from '@mks2508/better-logger';
+ *
+ * const stripe = logger.api('Stripe');
+ * stripe.info('Consultando customer', { id });
+ * // salida: [API:Stripe] [API] Consultando customer
  *
- * api.slow('Query lenta', 3500);
- * // [API] [SLOW] [REST] Query lenta (3500ms)
+ * stripe.slow('customer.retrieve', 1250);
+ * // salida: [API:Stripe] [API] [SLOW] customer.retrieve (1250ms)
  *
- * @since 0.3.0
+ * @see {@link Logger.api}
+ * @see {@link ScopedLogger}
  */
 export declare class APILogger extends ScopedLogger {
-    constructor(parentLogger: Logger, apiName: string, config?: Partial<LoggerConfig>);
     /**
-     * Registra operaciones lentas
+     * Construye un APILogger con scope `API:<apiName>` y badge `API` ya aplicado.
      *
-     * @param {string} message - Mensaje sobre la operación lenta
-     * @param {number} duration - Duración en milisegundos (opcional)
+     * Los clientes deben usar `logger.api(name)`.
      *
-     * @example
-     * api.slow('Query compleja', 5000);
-     * api.slow('Procesamiento pesado');
+     * @param {Logger} parent - Logger raíz al que se delegan los mensajes.
+     * @param {string} apiName - Nombre del servicio/API (se prefija con `API:`).
+     */
+    constructor(parent: Logger, apiName: string);
+    /**
+     * Registra una llamada lenta con badge `SLOW` a nivel `warn`.
+     *
+     * @param {string} message - Descripción de la operación lenta.
+     * @param {number} [duration] - Duración medida en ms; si se pasa, se
+     *   anexa al mensaje como `(Nms)`.
      *
-     * @since 0.3.0
+     * @example
+     * const t0 = performance.now();
+     * await stripe.customers.retrieve(id);
+     * logger.api('Stripe').slow('retrieve', performance.now() - t0);
      */
     slow(message: string, duration?: number): void;
     /**
-     * Registra límites de tasa alcanzados
+     * Registra un evento de rate limiting (HTTP 429) con badge `RATE_LIMIT`.
      *
-     * @param {string} message - Mensaje sobre el límite
+     * @param {string} message - Detalle del límite golpeado.
      *
      * @example
-     * api.rateLimit('Límite excedido: 100 req/min');
-     *
-     * @since 0.3.0
+     * logger.api('GitHub').rateLimit('Secondary rate limit on /search');
      */
     rateLimit(message: string): void;
     /**
-     * Registra problemas de autenticación
+     * Registra un fallo de autenticación (401/403) con badge `AUTH` a nivel
+     * `error`.
      *
-     * @param {string} message - Mensaje de autenticación
+     * @param {string} message - Detalle del fallo de credenciales/token.
      *
      * @example
-     * api.auth('Token inválido o expirado');
-     * api.auth('Credenciales incorrectas');
-     *
-     * @since 0.3.0
+     * logger.api('OAuth').auth('Token expirado');
      */
     auth(message: string): void;
     /**
-     * Registra advertencias de deprecación
+     * Marca una API como deprecada con badge `DEPRECATED` a nivel `warn`.
      *
-     * @param {string} message - Mensaje de deprecación
+     * @param {string} message - Mensaje guiando a la migración (endpoint
+     *   alternativo, versión retirada, etc.).
      *
      * @example
-     * api.deprecated('Este endpoint será eliminado en v2.0');
-     * api.deprecated('Usar /v2/users en lugar de /users');
-     *
-     * @since 0.3.0
+     * logger.api('Legacy').deprecated('Usar v3; v2 se retira en Q4');
      */
     deprecated(message: string): void;
 }
 /**
- * Logger específico para componentes de UI
+ * Logger para componentes UI, módulos o cualquier unidad con ciclo de vida.
  *
- * @class ComponentLogger
- * @extends ScopedLogger
- * @description Logger especializado para componentes con eventos de ciclo de vida
+ * Extiende {@link ScopedLogger} pre-seteando el badge `COMPONENT` y exponiendo
+ * atajos para eventos típicos: {@link lifecycle}, {@link stateChange} y
+ * {@link propsChange}.
+ *
+ * Se obtiene con `logger.component(name)` y no se construye directamente.
  *
  * @example
- * const authForm = logger.component('AuthForm');
- * authForm.lifecycle('mounted');
- * authForm.stateChange('idle', 'loading');
+ * import logger from '@mks2508/better-logger';
+ *
+ * const cart = logger.component('Cart');
+ * cart.lifecycle('mount');
+ * // salida: [Cart] [COMPONENT] [LIFECYCLE] mount
  *
- * @since 0.3.0
+ * cart.stateChange('empty', 'has-items', { count: 3 });
+ * // salida: [Cart] [COMPONENT] [STATE] empty → has-items { count: 3 }
+ *
+ * @see {@link Logger.component}
+ * @see {@link ScopedLogger}
  */
 export declare class ComponentLogger extends ScopedLogger {
-    constructor(parentLogger: Logger, componentName: string, config?: Partial<LoggerConfig>);
     /**
-     * Registra eventos del ciclo de vida del componente
+     * Construye un ComponentLogger con badge `COMPONENT` ya aplicado.
      *
-     * @param {string} event - Nombre del evento (mounted, unmounted, updated, etc)
-     * @param {string} message - Mensaje adicional (opcional)
+     * Los clientes deben usar `logger.component(name)`.
      *
-     * @example
-     * component.lifecycle('mounted', 'Componente listo');
-     * component.lifecycle('beforeDestroy');
+     * @param {Logger} parent - Logger raíz al que se delegan los mensajes.
+     * @param {string} componentName - Nombre del componente (scope label).
+     */
+    constructor(parent: Logger, componentName: string);
+    /**
+     * Registra un evento de ciclo de vida con badge `LIFECYCLE` a nivel `info`.
      *
-     * @since 0.3.0
+     * @param {string} event - Nombre del evento (`mount`, `unmount`,
+     *   `update`, ...).
+     * @param {string} [message] - Detalle opcional; si se omite, solo se
+     *   registra el nombre del evento.
+     *
+     * @example
+     * logger.component('Cart').lifecycle('mount', 'Modal abierto');
      */
     lifecycle(event: string, message?: string): void;
     /**
-     * Registra cambios de estado
+     * Registra una transición de estado con badge `STATE` a nivel `info`.
      *
-     * @param {string} from - Estado anterior
-     * @param {string} to - Estado nuevo
-     * @param {any} data - Datos adicionales (opcional)
+     * @param {string} from - Estado previo.
+     * @param {string} to - Estado nuevo.
+     * @param {unknown} [data] - Payload opcional asociado a la transición.
      *
      * @example
-     * component.stateChange('idle', 'loading');
-     * component.stateChange('loading', 'error', { code: 404 });
-     *
-     * @since 0.3.0
+     * const fsm = logger.component('FSM');
+     * fsm.stateChange('idle', 'loading');
+     * fsm.stateChange('loading', 'success', { items: 3 });
      */
-    stateChange(from: string, to: string, data?: any): void;
+    stateChange(from: string, to: string, data?: unknown): void;
     /**
-     * Registra cambios en las propiedades
+     * Registra cambios de props/debug del componente con badge `PROPS` a nivel
+     * `debug`.
      *
-     * @param {Record<string, any>} changes - Objeto con los cambios
+     * @param {Record<string, unknown>} changes - Mapa prop → valor (típicamente
+     *   el diff de props entre renders).
      *
      * @example
-     * component.propsChange({
-     *   user: newUser,
-     *   isActive: true
-     * });
-     *
-     * @since 0.3.0
+     * logger.component('Cart').propsChange({ itemCount: 5, currency: 'EUR' });
      */
-    propsChange(changes: Record<string, any>): void;
+    propsChange(changes: Record<string, unknown>): void;
 }
 /**
- * Logger de contexto temporal que se limpia automáticamente
+ * Handler de contexto apilable sobre un {@link ScopedLogger}.
+ *
+ * Permite agrupar bloques de logs bajo un sub-prefijo separado por `:`,
+ * manteniendo la correlación visual sin necesidad de `console.group`. El
+ * prefijo compuesto se forma como `<scopeName>:<contextName>`.
  *
- * @class ContextLogger
- * @description Proporciona un contexto temporal para operaciones agrupadas
+ * Se crea con `scopedLogger.context(name)`. El patrón idiomático es
+ * {@link run}/{@link runAsync} (auto push/pop con try/finally); {@link start}
+ * y {@link end} permiten control manual cuando el bloque no cierra
+ * léxicamente (event handlers distribuidos, promesas de larga duración).
  *
  * @example
- * const db = logger.scope('Database');
+ * import logger from '@mks2508/better-logger';
  *
- * // El contexto se limpia automáticamente al finalizar
- * db.context('Transaction').run(() => {
- *   db.info('Iniciando transacción');
- *   db.success('Transacción completada');
+ * const http = logger.scope('HTTP');
+ *
+ * // Bloque síncrono auto-cerrado
+ * http.context('retry').run(() => {
+ *   http.warn('Reintentando petición');
+ * });
+ * // salida: [HTTP:retry] Reintentando petición
+ *
+ * // Bloque async auto-cerrado
+ * await http.context('refresh').runAsync(async () => {
+ *   await refreshToken();
+ *   http.info('Token refrescado');
  * });
  *
- * @since 0.3.0
+ * @see {@link ScopedLogger.context}
  */
 export declare class ContextLogger {
     private parentLogger;
     private contextName;
+    /**
+     * @param {ScopedLogger} parentLogger - Scope sobre el que se apila el contexto.
+     * @param {string} contextName - Sub-prefijo a apilar en el scope padre.
+     */
     constructor(parentLogger: ScopedLogger, contextName: string);
     /**
-     * Ejecuta una función con este contexto activo
+     * Ejecuta `fn` síncrona dentro del contexto, garantizando el pop del
+     * prefijo incluso si `fn` lanza. El contexto solo está activo durante la
+     * ejecución de `fn`.
      *
-     * @template T - Tipo de retorno de la función
-     * @param {Function} fn - Función a ejecutar
-     * @returns {T} Resultado de la función
+     * @typeParam T - Tipo de retorno de `fn`.
+     * @param {() => T} fn - Función a ejecutar bajo el contexto.
+     * @returns {T} Lo que devuelva `fn`.
+     * @throws {unknown} Relanza cualquier excepción de `fn` tras desapilar.
      *
      * @example
-     * const result = logger.context('Process').run(() => {
-     *   logger.info('Procesando...');
-     *   return processData();
+     * logger.scope('HTTP').context('warmup').run(() => {
+     *   logger.info('Pre-cargando caché');
      * });
-     *
-     * @since 0.3.0
      */
     run<T>(fn: () => T): T;
     /**
-     * Run an async function with this context active
+     * Variante async de {@link run}: mantiene el contexto activo mientras se
+     * awaiting la promesa de `fn`, incluyendo awaits internos.
+     *
+     * @typeParam T - Tipo resuelto por la promesa de `fn`.
+     * @param {() => Promise<T>} fn - Función async a ejecutar bajo el contexto.
+     * @returns {Promise<T>} Promesa que resuelve al valor de `fn`.
+     * @throws {unknown} Relanza cualquier rechazo de `fn` tras desapilar.
+     *
+     * @example
+     * await logger.scope('HTTP').context('fetch').runAsync(async () => {
+     *   const r = await fetch(url);
+     *   logger.info('Recibido', { status: r.status });
+     * });
      */
     runAsync<T>(fn: () => Promise<T>): Promise<T>;
     /**
-     * Start the context (manual mode)
+     * Apila el contexto manualmente. Útil cuando el bloque que lo consume no
+     * cierra léxicamente (event handlers, timeouts, streams). Debe emparejarse
+     * con un {@link end} posterior; olvidarlo deja el prefijo contaminado para
+     * los logs siguientes del scope.
+     *
+     * @example
+     * const ctx = logger.scope('WS').context('subscribe');
+     * socket.onopen  = () => { ctx.start(); ctx.info('connected'); };
+     * socket.onclose = () => { ctx.info('disconnected'); ctx.end(); };
+     * @see {@link end}
      */
     start(): void;
     /**
-     * End the context (manual mode)
+     * Desapila el último contexto abierto con {@link start}.
+     *
+     * @see {@link start}
      */
     end(): void;
-    debug(...args: any[]): void;
-    info(...args: any[]): void;
-    warn(...args: any[]): void;
-    error(...args: any[]): void;
-    success(...args: any[]): void;
-    critical(...args: any[]): void;
+    /**
+     * Atajo a `scopedLogger.debug(...)`. El contexto se aplica al prefijo del
+     * scope padre solo si se invoca dentro de un bloque {@link run}/{@link start}.
+     *
+     * @param {...unknown[]} args - Mensaje y argumentos adicionales.
+     */
+    debug(...args: unknown[]): void;
+    /**
+     * Atajo a `scopedLogger.info(...)`. El contexto se aplica al prefijo del
+     * scope padre solo si se invoca dentro de un bloque {@link run}/{@link start}.
+     *
+     * @param {...unknown[]} args - Mensaje y argumentos adicionales.
+     */
+    info(...args: unknown[]): void;
+    /**
+     * Atajo a `scopedLogger.warn(...)`. El contexto se aplica al prefijo del
+     * scope padre solo si se invoca dentro de un bloque {@link run}/{@link start}.
+     *
+     * @param {...unknown[]} args - Mensaje y argumentos adicionales.
+     */
+    warn(...args: unknown[]): void;
+    /**
+     * Atajo a `scopedLogger.error(...)`. El contexto se aplica al prefijo del
+     * scope padre solo si se invoca dentro de un bloque {@link run}/{@link start}.
+     *
+     * @param {...unknown[]} args - Mensaje y argumentos adicionales.
+     */
+    error(...args: unknown[]): void;
+    /**
+     * Atajo a `scopedLogger.success(...)`. El contexto se aplica al prefijo del
+     * scope padre solo si se invoca dentro de un bloque {@link run}/{@link start}.
+     *
+     * @param {...unknown[]} args - Mensaje y argumentos adicionales.
+     */
+    success(...args: unknown[]): void;
+    /**
+     * Atajo a `scopedLogger.critical(...)`. El contexto se aplica al prefijo
+     * del scope padre solo si se invoca dentro de un bloque {@link run}/{@link start}.
+     *
+     * @param {...unknown[]} args - Mensaje y argumentos adicionales.
+     */
+    critical(...args: unknown[]): void;
 }
 //# sourceMappingURL=ScopedLogger.d.ts.map