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

package/dist/styling/banners.d.ts

@@ -1,9 +1,32 @@
 /**
- * @fileoverview Banner configurations for Advanced Logger
+ * @fileoverview Configuraciones de banner para Advanced Logger.
  */
 import type { BannerType, ThemeVariant } from '../types/index.js';
 /**
- * Banner variants for different display capabilities
+ * Catálogo de variantes del banner de inicialización del logger.
+ *
+ * Cada variante es un par `{ text, style }` listo para pasar a
+ * `console.log(\`%c${text}\`, style)`. Las variantes escalan en complejidad
+ * visual según las capacidades del navegador:
+ *  - `simple`   — una sola línea con gradiente.
+ *  - `ascii`    — ASCII art multiníveles (Safari, sin SVG).
+ *  - `unicode`  — caja Unicode con gradiente de fondo.
+ *  - `svg`      — `background-image` SVG con texto vectorial.
+ *  - `animated` — gradiente animado vía `@keyframes gradientShift`.
+ *
+ * La función {@link detectBannerCapabilities} elige automáticamente la
+ * variante más rica soportada por el entorno actual.
+ *
+ * @example
+ * ```ts
+ * import { BANNER_VARIANTS } from '@mks2508/better-logger/styles';
+ *
+ * const { text, style } = BANNER_VARIANTS.unicode;
+ * console.log(`%c${text}`, style);
+ * ```
+ *
+ * @see {@link BannerType} para la unión de claves válidas.
+ * @see {@link displayInitBanner} para pintar el banner auto-detectado.
  */
 export declare const BANNER_VARIANTS: {
     simple: {
@@ -28,22 +51,75 @@ export declare const BANNER_VARIANTS: {
     };
 };
 /**
- * Theme-specific banners for enhanced visual theming
+ * Banners de inicialización específicos por {@link ThemeVariant}.
+ *
+ * Cada theme trae su propio par `{ simple, style }` (banner de una línea
+ * + CSS) que combina con la paleta del theme. El texto del banner es
+ * siempre una sola línea (sin ASCII art), por lo que es la variante
+ * usada por defecto cuando el logger arranca con un theme concreto.
+ *
+ * @example
+ * ```ts
+ * import { THEME_BANNERS } from '@mks2508/better-logger/styles';
+ *
+ * const { simple, style } = THEME_BANNERS.cyberpunk;
+ * console.log(`%c${simple}`, style);
+ * ```
+ *
+ * @see {@link THEME_PRESETS} para los estilos de badge por nivel de cada theme.
+ * @see {@link ThemeVariant} para la lista de themes disponibles.
  */
 export declare const THEME_BANNERS: Record<ThemeVariant, {
     simple: string;
     style: string;
 }>;
 /**
- * Feature detection for banner capabilities. Returns `'simple'` immediately
- * if neither `navigator` nor `document` exist (Node, SSR, workers).
+ * Detecta la variante de banner más rica que el entorno puede renderizar.
  *
+ * Usa `navigator.userAgent` y probes sobre `document` para decidir entre
+ * `animated` (Chrome con CSS animations), `svg` (Chrome/Firefox con SVG),
+ * `unicode` (Chrome/Firefox fallback), `ascii` (Safari) o `simple`
+ * (todo lo demás). En entornos sin `navigator` o `document` retorna
+ * `'simple'` inmediatamente (Node, SSR, Web Workers).
+ *
+ * @returns {BannerType} Variante de banner recomendada para el entorno.
+ *
+ * @example
+ * ```ts
+ * import { detectBannerCapabilities } from '@mks2508/better-logger/styles';
+ *
+ * const capable = detectBannerCapabilities();
+ * console.log(`Best banner for this env: ${capable}`);
+ * ```
+ *
+ * @see {@link BANNER_VARIANTS} para el catálogo que indexa este resultado.
  */
 export declare function detectBannerCapabilities(): BannerType;
 /**
- * Display initialization banner with advanced styling. No-op in Node,
- * SSR, or Web Workers (DOM-guard at the top).
+ * Pinta el banner de inicialización del logger en la consola del navegador.
+ *
+ * Si no se pasa `bannerType`, se auto-detecta vía
+ * {@link detectBannerCapabilities}. Además del banner, abre un
+ * `console.group` con la lista de features soportadas (styling, stack
+ * traces, performance timers, handlers, ...).
+ *
+ * No-op cuando `document` no está disponible (Node, SSR, Web Workers),
+ * para evitar referencias a APIs inexistentes.
+ *
+ * @param {BannerType} [bannerType] - Variante de banner a pintar. Si se
+ *   omite, se detecta automáticamente la mejor soportada.
+ * @returns {void}
+ *
+ * @example
+ * ```ts
+ * import { displayInitBanner } from '@mks2508/better-logger/styles';
+ *
+ * displayInitBanner();          // auto-detecta
+ * displayInitBanner('ascii');   // fuerza ASCII art
+ * ```
  *
+ * @see {@link BANNER_VARIANTS} para las variantes disponibles.
+ * @see {@link THEME_BANNERS} para banners específicos por theme.
  */
 export declare function displayInitBanner(bannerType?: BannerType): void;
 //# sourceMappingURL=banners.d.ts.map

package/dist/styling/banners.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"banners.d.ts","sourceRoot":"","sources":["../../src/styling/banners.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAElE;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;CAoD3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,YAAY,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAyBjF,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,UAAU,CA8BrD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI,CAyC/D"}
+{"version":3,"file":"banners.d.ts","sourceRoot":"","sources":["../../src/styling/banners.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;CAoD3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,YAAY,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAyBjF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,IAAI,UAAU,CA8BrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI,CAyC/D"}

package/dist/styling/themes.d.ts

@@ -1,10 +1,49 @@
 /**
- * @fileoverview Theme presets for Advanced Logger
+ * @fileoverview Presets de themes visuales para Advanced Logger.
  */
 import type { ThemeVariant } from '../types/index.js';
 import type { LevelStyleConfig } from '../utils/index.js';
 /**
- * Theme configurations for different visual styles
+ * Catálogo de themes visuales para los badges de cada log level.
+ *
+ * Cada {@link ThemeVariant} mapea a un record de {@link LevelStyleConfig}
+ * indexado por nivel (`debug`, `info`, `warn`, `error`, `success`,
+ * `critical`). El {@link StyleManager} consume este mappeo para resolver
+ * los estilos CSS del badge que rodea al label del nivel en la consola
+ * del navegador.
+ *
+ * Un {@link LevelStyleConfig} por nivel define seis campos visuales:
+ *  - `emoji`      — glyph que precede al label (vacío en themes minimal).
+ *  - `label`      — texto en mayúsculas renderizado dentro del badge.
+ *  - `background` — CSS background (típicamente un `linear-gradient`).
+ *  - `color`      — color del texto interior del badge.
+ *  - `border`     — CSS border completo (`<width> <style> <color>`).
+ *  - `shadow`     — box-shadow alrededor del badge; `'none'` lo desactiva.
+ *
+ * Themes disponibles: `default` (gradientes vivos), `dark` (paleta oscura
+ * para DevTools oscuro), `neon` (glow neón sobre fondo oscuro), `minimal`
+ * (badges planos sin sombras ni emojis), `light` (paleta pastel para
+ * DevTools claro) y `cyberpunk` (cian/magenta con sombras extendidas).
+ *
+ * @example
+ * ```ts
+ * import { THEME_PRESETS } from '@mks2508/better-logger/styles';
+ *
+ * // Inspeccionar el badge `error` del theme `neon`
+ * const { emoji, label, background, color } = THEME_PRESETS.neon.error;
+ * console.log(`${emoji} ${label} → ${background}`);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Aplicar un theme al logger entero
+ * import logger from '@mks2508/better-logger';
+ * logger.configure({ theme: 'cyberpunk' });
+ * logger.error('Algo se rompió'); // badge con glow magenta
+ * ```
+ *
+ * @see {@link ThemeVariant} para la lista de claves válidas.
+ * @see {@link LevelStyleConfig} para la shape exacta de cada entrada.
  */
 export declare const THEME_PRESETS: Record<ThemeVariant, Record<string, LevelStyleConfig>>;
 //# sourceMappingURL=themes.d.ts.map

package/dist/styling/themes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"themes.d.ts","sourceRoot":"","sources":["../../src/styling/themes.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAgOhF,CAAC"}
+{"version":3,"file":"themes.d.ts","sourceRoot":"","sources":["../../src/styling/themes.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAmQhF,CAAC"}

package/dist/transports/ConsoleTransport.d.ts

@@ -1,9 +1,104 @@
 import type { TransportRecord, TransportOptions, ITransport } from '../types/index.js';
+/**
+ * Transport por defecto que escribe cada {@link TransportRecord} al `console`
+ * global del runtime (navegador o Node.js).
+ *
+ * Es el transport que el Logger registra automáticamente cuando no se configura
+ * ninguno explícito, garantizando que los registros siempre lleguen a un
+ * destino visible sin configuración adicional.
+ *
+ * **Mapeo level → console method**: traduce cada nivel de log al método más
+ * cercano de la API `console`, de forma que el filtrado nativo del DevTools /
+ * `NODE_DEBUG` siga funcionando:
+ *
+ * | LogLevel     | console method |
+ * |--------------|----------------|
+ * | `debug`      | `console.log`  |
+ * | `info`       | `console.info` |
+ * | `warn`       | `console.warn` |
+ * | `error`      | `console.error`|
+ * | `critical`   | `console.error`|
+ *
+ * **Formato de output**: cada línea se compone como
+ * `[LEVEL] [prefix] message (file:line)`, donde `prefix` y la localización
+ * se omiten si el registro no las trae.
+ *
+ * @example
+ * // Uso directo como ITransport
+ * import { ConsoleTransport } from '@mks2508/better-logger/transports';
+ * const transport = new ConsoleTransport();
+ * transport.write({
+ *   level: 'info',
+ *   msg: 'Arrancando worker',
+ *   prefix: 'worker',
+ *   // ... resto del TransportRecord
+ * });
+ * // → console.info("[INFO] [worker] Arrancando worker (worker.ts:12)")
+ *
+ * @example
+ * // Registro a través del Logger (típico — el logger lo añade por defecto)
+ * logger.addTransport({ target: new ConsoleTransport() });
+ *
+ * @see {@link ITransport}
+ * @see {@link TransportRecord}
+ */
 export declare class ConsoleTransport implements ITransport {
     private options?;
+    /** Identificador del transport usado por el Logger para deduplicar y exponer metadatos. */
     readonly name = "console";
+    /**
+     * Crea una instancia de {@link ConsoleTransport}.
+     *
+     * El parámetro `options` se acepta para cumplir con la firma canónica de
+     * {@link TransportOptions} (filtros de nivel, formateadores, etc.), aunque
+     * la implementación actual escribe el registro tal cual llega sin
+     * transformaciones adicionales.
+     *
+     * @param {TransportOptions} [options] - Configuración opcional del transport
+     * (nivel mínimo, formatter, etc.).
+     *
+     * @example
+     * const transport = new ConsoleTransport({ level: 'warn' });
+     */
     constructor(options?: TransportOptions | undefined);
+    /**
+     * Escribe un {@link TransportRecord} al `console` global.
+     *
+     * Selecciona el método de console según el nivel del registro, compone el
+     * prefijo `[LEVEL] [prefix]` y, si la localización está disponible, añade
+     * el sufijo `(file:line)`. No lanza ni retorna errores: si `console[method]`
+     * fallara (raro), la excepción propagaría al caller.
+     *
+     * @param {TransportRecord} record - Registro normalizado producido por el Logger.
+     * @returns {void}
+     *
+     * @example
+     * transport.write({
+     *   level: 'error',
+     *   msg: 'DB connection lost',
+     *   prefix: 'db',
+     *   location: { file: 'pool.ts', line: 87, function: 'acquire' },
+     *   // ... resto del TransportRecord
+     * });
+     * // → console.error("[ERROR] [db] DB connection lost (pool.ts:87)")
+     */
     write(record: TransportRecord): void;
+    /**
+     * Resuelve el método de `console` apropiado para un {@link LogLevel}.
+     *
+     * Tabla de mapeo:
+     * - `debug`    → `log`    (sin ruido en DevTools por defecto)
+     * - `info`     → `info`
+     * - `warn`     → `warn`
+     * - `error`    → `error`
+     * - `critical` → `error`  (no existe `console.critical`)
+     * - cualquier otro → `log` (fallback seguro)
+     *
+     * @internal Método privado; no forma parte de la API pública del transport.
+     *
+     * @param {LogLevel} level - Nivel del registro a traducir.
+     * @returns {'log' | 'info' | 'warn' | 'error'} Nombre del método de `console`.
+     */
     private getConsoleMethod;
 }
 //# sourceMappingURL=ConsoleTransport.d.ts.map

package/dist/transports/ConsoleTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConsoleTransport.d.ts","sourceRoot":"","sources":["../../src/transports/ConsoleTransport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,UAAU,EAAY,MAAM,mBAAmB,CAAC;AAEjG,qBAAa,gBAAiB,YAAW,UAAU;IAGnC,OAAO,CAAC,OAAO,CAAC;IAF5B,QAAQ,CAAC,IAAI,aAAa;gBAEN,OAAO,CAAC,EAAE,gBAAgB,YAAA;IAE9C,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAUpC,OAAO,CAAC,gBAAgB;CAU3B"}
+{"version":3,"file":"ConsoleTransport.d.ts","sourceRoot":"","sources":["../../src/transports/ConsoleTransport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,UAAU,EAAY,MAAM,mBAAmB,CAAC;AAEjG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IAkBnC,OAAO,CAAC,OAAO,CAAC;IAjB5B,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,aAAa;IAE1B;;;;;;;;;;;;;OAaG;gBACiB,OAAO,CAAC,EAAE,gBAAgB,YAAA;IAE9C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAUpC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,gBAAgB;CAU3B"}

package/dist/transports/FileTransport.d.ts

@@ -1,53 +1,134 @@
 import type { TransportRecord, TransportOptions, IBufferedTransport, HookLogEntry } from '../types/index.js';
 /**
- * Options for {@link FileTransport}. Uses `destination` as the file path in
- * Node and as a `localStorage` key in the browser (the path component is
- * sanitised to `[a-zA-Z0-9_-]`).
+ * Opciones para {@link FileTransport}. El campo `destination` se interpreta
+ * como ruta de fichero en Node y como clave de `localStorage` en el browser
+ * (componente saneado a `[a-zA-Z0-9_-]`).
  *
+ * Hereda los defaults de {@link TransportOptions}: `batchSize=100`,
+ * `maxBufferSize=10000`.
+ *
+ * @example
+ * const transport = new FileTransport({
+ *   destination: 'logs/app.log',
+ *   batchSize: 200,
+ *   flushInterval: 2000,
+ *   maxBufferSize: 5000,
+ *   onError: (entry) => captureFailure(entry)
+ * });
  */
 export interface FileTransportOptions extends TransportOptions {
     /**
-     * Where to write. In Node this is a file path (resolved relative to
-     * `process.cwd()` and sanitised against path traversal). In the browser
-     * this is a localStorage key (sanitised to alphanumeric + `-_`).
+     * Destino de escritura. En Node es una ruta de fichero (resuelta relativa
+     * a `process.cwd()` y saneada contra path traversal). En el browser es una
+     * clave de `localStorage` (saneada a alfanumérico + `-_`).
      * @default 'app.log' (Node) | 'better-logger:default' (browser)
      */
     destination?: string;
     /**
-     * Optional hook fired when the transport cannot write (FS error,
-     * quota exceeded, browser tab in private mode, ...). Receives a
-     * synthetic {@link HookLogEntry}.
+     * Hook opcional que se dispara cuando el transport no puede escribir
+     * (error de FS, quota agotada, tab del browser en modo privado, ...).
+     * Recibe un {@link HookLogEntry} sintético.
      */
     onError?: (entry: HookLogEntry) => void | Promise<void>;
 }
 /**
- * File-based transport.
+ * Transport que escribe registros a fichero (Node) o `localStorage` (browser).
+ *
+ * En Node, hace `appendFile` asíncrono vía `fs.promises` cargado con dynamic
+ * import (no bloquea el event loop, no envía código Node-only al bundle del
+ * browser). En el browser, acumula en `localStorage` con prefijo `better-logger:`
+ * y degrada a no-op silencioso si el storage no está disponible (modo privado,
+ * sandbox de iframes, quota agotada).
+ *
+ * El buffer es bounded: al llegar a `maxBufferSize` suelta el registro más
+ * viejo (drop-oldest) e invoca `onError` con el payload descartado, de modo
+ * que un pico de tráfico sostenido no agota memoria.
+ *
+ * El `destination` se sanea antes de usarse:
+ * - Node: se rechazan rutas con segmentos `..`, `~` o absolutas (path traversal).
+ * - Browser: se colapsa a `[a-zA-Z0-9_-]` recortado a 64 caracteres.
  *
- * - In Node, writes batches via `fs.promises.appendFile` (non-blocking).
- * - In the browser, writes batches into `localStorage` (fallback no-op if
- *   `localStorage` is unavailable — e.g. private mode, sandboxed iframes).
+ * @implements {IBufferedTransport}
  *
- * Fixed in 5.1.0:
- *   - BUG-N3: uses async `fs.promises.appendFile` instead of sync `appendFileSync`.
- *   - BUG-N4: destination is sanitised to reject path traversal (`..`, `~`, abs paths).
- *   - BUG-N5: dynamic `import('node:fs/promises')` instead of CJS `require('fs')`.
- *   - BUG-N6: browser case uses `localStorage` with try/catch (was silent no-op).
+ * @example
+ * // Node: append a fichero con flush cada segundo
+ * logger.addTransport({
+ *   target: new FileTransport({
+ *     destination: 'logs/app.log',
+ *     batchSize: 100,
+ *     flushInterval: 1000,
+ *     onError: (entry) => captureFailure(entry)
+ *   })
+ * });
  *
+ * @example
+ * // Browser: persiste en localStorage bajo 'better-logger:audit'
+ * logger.addTransport({
+ *   target: new FileTransport({ destination: 'audit' })
+ * });
+ *
+ * @see {@link FileTransportOptions}
+ * @see {@link IBufferedTransport}
  */
 export declare class FileTransport implements IBufferedTransport {
+    /** Identificador del transport dentro del pipeline (`'file'`). */
     readonly name = "file";
     private buffer;
     private flushTimer?;
     private options;
     private closed;
+    /**
+     * Construye el transport. Si se pasa `flushInterval`, arranca un timer
+     * periódico que vacía el buffer al vencimiento; si no, el flush se
+     * dispara solo cuando el buffer alcanza `batchSize`.
+     *
+     * @param {FileTransportOptions} [options] - Configuración. Defaults: `batchSize=100`, `maxBufferSize=10000`.
+     *
+     * @example
+     * const t = new FileTransport({ destination: 'app.log', flushInterval: 1000 });
+     */
     constructor(options?: FileTransportOptions);
+    /** Registros pendientes en el buffer (aún sin flush). */
     get bufferSize(): number;
+    /** Capacidad máxima del buffer; al superarla se aplica drop-oldest. */
     get maxBufferSize(): number;
+    /**
+     * Indica si el transport acepta escrituras. Devuelve `false` después de
+     * {@link FileTransport.close} — cualquier `write` posterior se descarta.
+     *
+     * @returns {boolean} `true` mientras el transport no esté cerrado.
+     */
     isReady(): boolean;
+    /**
+     * Encola un registro serializado (JSON + `\n`). Si el buffer está a tope,
+     * suelta el registro más viejo (drop-oldest) y emite un evento `onError`
+     * con el payload descartado para que la pérdida sea observable. Si al
+     * encolar se alcanza `batchSize`, dispara un flush asíncrono.
+     *
+     * No-op silencioso si el transport está cerrado.
+     *
+     * @param {TransportRecord} record - Registro a escribir.
+     */
     write(record: TransportRecord): void;
+    /**
+     * Vuelca el buffer al destino. En Node concatena el contenido y hace
+     * un único `appendFile`; en browser hace un único `setItem` sobre
+     * `localStorage`. El buffer se vacía antes del I/O para que los registros
+     * entrantes no esperen al disco. Los errores de escritura se reportan
+     * vía `onError` (nunca lanzan al caller).
+     *
+     * @returns {Promise<void>} Resuelve cuando el I/O terminó o falló.
+     */
     flush(): Promise<void>;
     private flushNode;
     private flushBrowser;
+    /**
+     * Cierra el transport: detiene el timer de flush y dispara un flush
+     * final para no perder registros pendientes. Tras cerrar, `write` y
+     * `flush` se vuelven no-op.
+     *
+     * @returns {Promise<void>} Resuelve cuando el flush final termina.
+     */
     close(): Promise<void>;
     private resolveNodeDestination;
     private resolveBrowserKey;

package/dist/transports/FileTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileTransport.d.ts","sourceRoot":"","sources":["../../src/transports/FileTransport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,eAAe,EACf,gBAAgB,EAEhB,kBAAkB,EAClB,YAAY,EAEf,MAAM,mBAAmB,CAAC;AAO3B;;;;;GAKG;AACH,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC1D;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,YAAW,kBAAkB;IACpD,QAAQ,CAAC,IAAI,UAAU;IAEvB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,UAAU,CAAC,CAAiC;IACpD,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,CAAC,EAAE,oBAAoB;IAc1C,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,OAAO,IAAI,OAAO;IAIlB,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IA+B9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAad,SAAS;YAaT,YAAY;IAcpB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,SAAS;CAYpB"}
+{"version":3,"file":"FileTransport.d.ts","sourceRoot":"","sources":["../../src/transports/FileTransport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,eAAe,EACf,gBAAgB,EAEhB,kBAAkB,EAClB,YAAY,EAEf,MAAM,mBAAmB,CAAC;AAO3B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC1D;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,aAAc,YAAW,kBAAkB;IACpD,kEAAkE;IAClE,QAAQ,CAAC,IAAI,UAAU;IAEvB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,UAAU,CAAC,CAAiC;IACpD,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;;;;;;OASG;gBACS,OAAO,CAAC,EAAE,oBAAoB;IAc1C,yDAAyD;IACzD,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,uEAAuE;IACvE,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;;;;OAKG;IACH,OAAO,IAAI,OAAO;IAIlB;;;;;;;;;OASG;IACH,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IA6BpC;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAad,SAAS;YAaT,YAAY;IAc1B;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,SAAS;CAYpB"}

package/dist/transports/HttpTransport.d.ts

@@ -1,67 +1,180 @@
 import type { TransportRecord, TransportOptions, IBufferedTransport, HookLogEntry } from '../types/index.js';
 /**
- * Configuration for {@link HttpTransport}. Extends {@link TransportOptions}
- * with HTTP-specific knobs.
+ * Configuración para {@link HttpTransport}. Extiende {@link TransportOptions}
+ * con parámetros HTTP: URL destino, headers custom, buffer acotado,
+ * retry con backoff para fallos transitorios, timeout de fetch por intento, y
+ * un hook `onError` que reporta drops (overflow / 4xx / retry exhausto)
+ * sin escalar excepciones al caller.
  *
+ * @example
+ * // Mínimo: solo URL
+ * new HttpTransport({ url: 'https://logs.example.com/ingest' });
+ *
+ * @example
+ * // Con retry/backoff ajustado y hook de errores
+ * new HttpTransport({
+ *   url: 'https://logs.example.com/ingest',
+ *   headers: { Authorization: 'Bearer <REDACTED>' },
+ *   maxRetries: 5,
+ *   initialBackoffMs: 500,
+ *   maxBackoffMs: 30_000,
+ *   fetchTimeoutMs: 5_000,
+ *   onError: (entry) => metrics.increment('log_drop', { reason: entry.message })
+ * });
  */
 export interface HttpTransportOptions extends TransportOptions {
-    /** Target URL. POST is used with a JSON-encoded body. */
+    /** URL destino. Se usa POST con body JSON. */
     url?: string;
-    /** Extra request headers (e.g. `Authorization: Bearer ...`). */
+    /** Headers extra de la request (ej. `Authorization: Bearer ...`). */
     headers?: Record<string, string>;
-    /** Hard cap on buffered records. Older entries dropped on overflow. */
+    /** Tope máximo de records en buffer. En overflow se dropea el más viejo. */
     maxBufferSize?: number;
-    /** Max consecutive retry attempts per batch before the entries are dropped. */
+    /** Reintentos consecutivos por batch antes de dropear los records. */
     maxRetries?: number;
-    /** Initial backoff in ms. Doubles per attempt up to `maxBackoffMs`. */
+    /** Backoff inicial en ms. Duplica por intento hasta `maxBackoffMs`. */
     initialBackoffMs?: number;
-    /** Backoff ceiling in ms. */
+    /** Techo de backoff en ms. */
     maxBackoffMs?: number;
-    /** Fetch timeout in ms (per attempt). Default 10_000. */
+    /** Timeout del fetch en ms (por intento). Default 10_000. */
     fetchTimeoutMs?: number;
     /**
-     * Optional hook fired when the buffer overflows or a batch is dropped
-     * after `maxRetries`. The hook receives a synthetic {@link HookLogEntry}.
+     * Hook opcional que se dispara cuando el buffer hace overflow o un batch
+     * se dropea tras `maxRetries`. Recibe una entrada {@link HookLogEntry}
+     * sintética.
      */
     onError?: (entry: HookLogEntry) => void | Promise<void>;
 }
 /**
- * HTTP-based transport. Buffers records, batches them on size or interval,
- * POSTs the batch as JSON, and surfaces failures via retry, bounded buffer,
- * and an `onError` hook — never a silent `.catch(() => {})`.
+ * Transport basado en HTTP. Bufferea records, los batcha por tamaño o
+ * intervalo, POSTea el batch como JSON, y reporta fallos vía retry, buffer
+ * acotado y un hook `onError` — nunca un `.catch(() => {})` silencioso.
+ *
+ * Lifecycle de cada batch (driveado internamente por `sendWithRetry`):
+ *  1. `fetch(url, { method: 'POST', body, signal })` con un `AbortController`
+ *     que aborta tras `fetchTimeoutMs`.
+ *  2. Si `response.ok` → batch considerado entregado.
+ *  3. Si `4xx` → dropeado sin reintento: el cliente nunca se recupera de un
+ *     error de URL/auth/payload mal formado. Se dispara `onError`.
+ *  4. Si `5xx` o `fetch` lanza (red caída / abort por timeout) → reintento con
+ *     backoff exponencial: arranca en `initialBackoffMs`, duplica por intento,
+ *     techo `maxBackoffMs`, hasta `maxRetries` intentos. Tras el agotamiento
+ *     el batch se re-bufferiza (o se trimea contra `maxBufferSize`) y se
+ *     dispara `onError` con `droppedCount`.
+ *
+ * El body por defecto es el envelope JSON `{ logs: TransportRecord[] }`.
+ * Para cambiar el wire format, sobrescribe los hooks `protected`
+ * {@link HttpTransport.serializeBody} y {@link HttpTransport.buildHeaders}
+ * (referencia: {@link OtlpTransport}).
+ *
+ * Extender esta clase es la vía recomendada para shippear un transport
+ * nuevo orientado a HTTP.
  *
- * Extending this class is the recommended way to ship a new transport:
- * see {@link OtlpTransport}.
+ * @example
+ * // Registro en un logger
+ * import logger from '@mks2508/better-logger';
+ * import { HttpTransport } from '@mks2508/better-logger/transports';
  *
+ * logger.addTransport({
+ *   target: new HttpTransport({
+ *     url: 'https://logs.example.com/ingest',
+ *     flushInterval: 5_000,
+ *     batchSize: 100,
+ *     onError: (entry) => console.error('[log-drop]', entry.message)
+ *   })
+ * });
+ *
+ * @see {@link HttpTransportOptions}
+ * @see {@link OtlpTransport}
  */
 export declare class HttpTransport implements IBufferedTransport {
+    /** Identificador del transport. Los loggers lo usan para lookup, dedup y logs de diagnóstico. */
     readonly name: string;
     private buffer;
     private flushTimer?;
     private closed;
-    /** Options bag — `protected` so subclasses (e.g. {@link OtlpTransport}) can read or extend it. */
+    /** Bag de options — `protected` para que subclasses (ej. {@link OtlpTransport}) puedan leerlo o extenderlo. */
     protected options: HttpTransportOptions;
+    /**
+     * Crea una instancia de {@link HttpTransport}.
+     *
+     * Los campos omitidos en `options` se rellenan con defaults sensatos
+     * (`batchSize=50`, `maxBufferSize=10_000`, `maxRetries=3`,
+     * `initialBackoffMs=250`, `maxBackoffMs=5_000`, `fetchTimeoutMs=10_000`).
+     * Si se pasa `flushInterval`, arranca un `setInterval` que flushea cada
+     * N ms; si se omite, el flush solo dispara por llenado de `batchSize`.
+     *
+     * @param {HttpTransportOptions} [options] - Configuración opcional. Si se omite por completo, el transport queda inactivo hasta que se setee `options.url` por otra vía (subclasses).
+     *
+     * @example
+     * const t = new HttpTransport({
+     *   url: 'https://logs.example.com/ingest',
+     *   flushInterval: 5_000
+     * });
+     */
     constructor(options?: HttpTransportOptions);
+    /** Records actualmente encolados esperando el próximo flush. */
     get bufferSize(): number;
+    /** Capacidad máxima del buffer. Al superarla, el registro más viejo se dropea y se notifica vía `onError`. */
     get maxBufferSize(): number;
+    /**
+     * Indica si el transport está listo para aceptar y entregar records.
+     * Devuelve `false` tras {@link close} o si no se configuró `url`.
+     *
+     * @returns {boolean} `true` si el transport puede enviar.
+     */
     isReady(): boolean;
+    /**
+     * Encola un record en el buffer. Si el buffer está lleno, aplica la
+     * política de overflow (dropea el más viejo + dispara `onError`). Si tras
+     * el push se alcanza `batchSize`, dispara un flush asíncrono (sin await).
+     *
+     * No-op si el transport ya fue cerrado ({@link close}).
+     *
+     * @param {TransportRecord} record - Registro a encolar.
+     */
     write(record: TransportRecord): void;
     /**
-     * Serialises a batch into the request body. Subclasses override to
-     * switch encodings (e.g. {@link OtlpTransport} produces OTLP/HTTP JSON
-     * instead of the default `{ logs: [...] }` envelope).
+     * Serializa un batch al body de la request. Las subclasses sobrescriben
+     * para cambiar la codificación (ej. {@link OtlpTransport} produce OTLP/HTTP
+     * JSON en vez del envelope default `{ logs: [...] }`).
      *
      */
     protected serializeBody(records: TransportRecord[]): string;
     /**
-     * Builds the request headers. Subclasses may prepend transport-specific
-     * headers (e.g. `signoz-ingestion-key`).
+     * Construye los headers de la request. Las subclasses pueden prependear
+     * headers transport-specific (ej. `signoz-ingestion-key`).
      *
      */
     protected buildHeaders(): Record<string, string>;
     private applyOverflowPolicy;
+    /**
+     * Flushea el buffer actual: toma un snapshot de los records pendientes,
+     * los envía con retry/backoff vía `sendWithRetry`, y ante fallo los
+     * re-bufferiza preservando el orden. Si la re-bufferización excede
+     * `maxBufferSize`, trimea los más viejos y dispara `onError` con
+     * `droppedCount`.
+     *
+     * No-op si el transport está cerrado, el buffer está vacío o no hay
+     * `url` configurada.
+     *
+     * @returns {Promise<void>} Resuelve cuando el intento de entrega del batch actual terminó (success, drop definitivo o no-op).
+     *
+     * @see {@link HttpTransportOptions.onError}
+     */
     flush(): Promise<void>;
     private sendWithRetry;
+    /**
+     * Cierra el transport: marca el flag `closed`, detiene el timer de
+     * `flushInterval` si estaba corriendo, y ejecuta un flush final para
+     * entregar lo pendiente.
+     *
+     * Tras `close()`, todo {@link write} posterior es no-op y
+     * {@link isReady} devuelve `false`.
+     *
+     * @returns {Promise<void>} Resuelve cuando el flush final termina.
+     *
+     * @see {@link flush}
+     */
     close(): Promise<void>;
 }
 //# sourceMappingURL=HttpTransport.d.ts.map