@mks2508/better-logger 0.14.0-alpha.2 → 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,18 +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
+ * 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
+ * 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;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,UAAU,CA2BrD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI,CAuC/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/index.d.ts

@@ -1,10 +1,15 @@
 /**
- * @fileoverview Styling system exports for Advanced Logger
+ * @fileoverview Styling system exports for Advanced Logger.
+ *
+ * Implementation-level primitives consumed by `src/styles/` (the public
+ * StyleManager bridge). End users should prefer:
+ *
+ * ```ts
+ * import { StyleBuilder, THEME_PRESETS } from '@mks2508/better-logger/styles';
+ * ```
  */
 export { StyleBuilder, $, StylePresets } from './StyleBuilder.js';
 export { THEME_PRESETS } from './themes.js';
 export { BANNER_VARIANTS, THEME_BANNERS, detectBannerCapabilities, displayInitBanner } from './banners.js';
-export { TimestampStyler, LevelStyler, PrefixStyler, MessageStyler, LocationStyler } from './SemanticStyles.js';
-export { LogStyleBuilder, createLogStyleBuilder } from './LogStyleBuilder.js';
 export { SMART_PRESETS, getSmartPreset, getAvailablePresets, hasPreset, PRESET_DESCRIPTIONS } from './SmartPresets.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/styling/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EACH,eAAe,EACf,aAAa,EACb,wBAAwB,EACxB,iBAAiB,EACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACH,eAAe,EACf,WAAW,EACX,YAAY,EACZ,aAAa,EACb,cAAc,EACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EACH,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,SAAS,EACT,mBAAmB,EACtB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/styling/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EACH,eAAe,EACf,aAAa,EACb,wBAAwB,EACxB,iBAAiB,EACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACH,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,SAAS,EACT,mBAAmB,EACtB,MAAM,mBAAmB,CAAC"}

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/terminal/color-converter.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Color Converter - CSS colors to ANSI extended color codes
+ * Supports 256-color and truecolor (24-bit) terminals
+ */
+export type ColorCapability = 'full' | 'basic' | 'none';
+export interface RGB {
+    r: number;
+    g: number;
+    b: number;
+}
+export declare function hexToRgb(hex: string): RGB;
+export declare function rgbToHex(r: number, g: number, b: number): string;
+export declare function hexTo256(hex: string): number;
+export declare function colorToHex(color: string): string;
+export declare function getANSIForeground(color: string, capability: ColorCapability): string;
+export declare function getANSIBackground(color: string, capability: ColorCapability): string;
+export declare function getANSI256Foreground(colorIndex: number): string;
+export declare function getANSI256Background(colorIndex: number): string;
+export declare function extractGradientColors(gradient: string): string[];
+export declare function gradientToSingleColor(gradient: string): string;
+export declare function cssColorToANSI(cssColor: string, capability: ColorCapability, isBackground?: boolean): string;
+export declare const ANSI: {
+    reset: string;
+    bold: string;
+    dim: string;
+    italic: string;
+    underline: string;
+    blink: string;
+    inverse: string;
+    hidden: string;
+    strikethrough: string;
+    fg: {
+        black: string;
+        red: string;
+        green: string;
+        yellow: string;
+        blue: string;
+        magenta: string;
+        cyan: string;
+        white: string;
+        gray: string;
+        brightRed: string;
+        brightGreen: string;
+        brightYellow: string;
+        brightBlue: string;
+        brightMagenta: string;
+        brightCyan: string;
+        brightWhite: string;
+    };
+    bg: {
+        black: string;
+        red: string;
+        green: string;
+        yellow: string;
+        blue: string;
+        magenta: string;
+        cyan: string;
+        white: string;
+        gray: string;
+        brightRed: string;
+        brightGreen: string;
+        brightYellow: string;
+        brightBlue: string;
+        brightMagenta: string;
+        brightCyan: string;
+        brightWhite: string;
+    };
+    rgb: (r: number, g: number, b: number) => string;
+    bgRgb: (r: number, g: number, b: number) => string;
+    color256: (n: number) => string;
+    bgColor256: (n: number) => string;
+};
+//# sourceMappingURL=color-converter.d.ts.map

package/dist/terminal/color-converter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-converter.d.ts","sourceRoot":"","sources":["../../src/terminal/color-converter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,GAAG;IAChB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb;AAiED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAUzC;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAc5C;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAoBhD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,GAAG,MAAM,CAmBpF;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,GAAG,MAAM,CAmBpF;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE/D;AAiCD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAehE;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAW9D;AAED,wBAAgB,cAAc,CAC1B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,eAAe,EAC3B,YAAY,GAAE,OAAe,GAC9B,MAAM,CAcR;AAED,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAiDJ,MAAM,KAAK,MAAM,KAAK,MAAM;eAC1B,MAAM,KAAK,MAAM,KAAK,MAAM;kBACzB,MAAM;oBACJ,MAAM;CACzB,CAAC"}

package/dist/terminal/formatter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Terminal Formatter - Alignment, key-value, and advanced terminal formatting
+ */
+import { type ColorCapability } from './color-converter.js';
+import type { ColumnConfig, ColumnAlign, BadgeStyle, TimestampFormat, LogOptions } from '../types/index.js';
+export declare function stripAnsi(str: string): string;
+export declare function getVisibleLength(str: string): number;
+export declare function padToWidth(str: string, width: number, align?: ColumnAlign): string;
+export declare function formatWithRightAlign(leftContent: string, rightContent: string, maxWidth?: number): string;
+export declare function formatColumns(columns: ColumnConfig[], maxWidth?: number, colorCapability?: ColorCapability): string;
+export declare function formatKeyValue(obj: Record<string, unknown>, colorCapability?: ColorCapability, options?: {
+    separator?: string;
+    keyColor?: string;
+    valueColor?: string;
+}): string;
+export declare function isKeyValueObject(obj: unknown): obj is Record<string, unknown>;
+export declare function formatBadge(badge: string, style?: BadgeStyle, colorCapability?: ColorCapability, color?: string): string;
+export declare function formatTimestamp(date?: Date, format?: TimestampFormat): string;
+export declare function formatRelativeTime(date: Date): string;
+export declare function formatElapsedTime(date: Date): string;
+export declare function resetStartTime(): void;
+export declare function applyLogOptions(message: string, options: LogOptions, colorCapability?: ColorCapability): string;
+//# sourceMappingURL=formatter.d.ts.map

package/dist/terminal/formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../../src/terminal/formatter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAA8C,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACxG,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE5G,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,WAAoB,GAAG,MAAM,CAiB1F;AAED,wBAAgB,oBAAoB,CAChC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,GAClB,MAAM,CAWR;AAED,wBAAgB,aAAa,CACzB,OAAO,EAAE,YAAY,EAAE,EACvB,QAAQ,CAAC,EAAE,MAAM,EACjB,eAAe,GAAE,eAAwB,GAC1C,MAAM,CA2BR;AAED,wBAAgB,cAAc,CAC1B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,eAAe,GAAE,eAAwB,EACzC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7E,MAAM,CA0BR;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAc7E;AAED,wBAAgB,WAAW,CACvB,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,UAAuB,EAC9B,eAAe,GAAE,eAAwB,EACzC,KAAK,CAAC,EAAE,MAAM,GACf,MAAM,CA4BR;AAED,wBAAgB,eAAe,CAC3B,IAAI,GAAE,IAAiB,EACvB,MAAM,GAAE,eAAwB,GACjC,MAAM,CAmBR;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAgBrD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAWpD;AAED,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED,wBAAgB,eAAe,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,eAAe,GAAE,eAAwB,GAC1C,MAAM,CAQR"}

package/dist/transports/ConsoleTransport.d.ts

@@ -0,0 +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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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

@@ -0,0 +1,137 @@
+import type { TransportRecord, TransportOptions, IBufferedTransport, HookLogEntry } from '../types/index.js';
+/**
+ * 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 {
+    /**
+     * 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;
+    /**
+     * 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>;
+}
+/**
+ * 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.
+ *
+ * @implements {IBufferedTransport}
+ *
+ * @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;
+    private emitError;
+}
+//# sourceMappingURL=FileTransport.d.ts.map

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

@@ -0,0 +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;;;;;;;;;;;;;;;;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"}