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

package/dist/types/core.d.ts

@@ -1,6 +1,3 @@
-/**
- * @fileoverview Definiciones de tipos principales para Better Logger
- */
 /**
  * Niveles de log soportados en orden jerárquico
  * (trace < debug < info < warn < error < critical)
@@ -33,15 +30,15 @@ export declare const LOG_LEVELS: {
  */
 export type LogLevel = keyof typeof LOG_LEVELS;
 /**
- * Special "level" tag used by `success()` — maps to OTel INFO severity.
- * Exists outside the standard LogLevel union so internal level comparisons
- * (trace < debug < info < warn < error < critical) are not perturbed.
+ * Tag especial de "nivel" usado por `success()` — mapea a severidad INFO de OTel.
+ * Vive fuera del union `LogLevel` estándar para que las comparaciones internas
+ * de nivel (trace < debug < info < warn < error < critical) no se vean alteradas.
  */
 export declare const SUCCESS_LEVEL: "success";
 /**
- * Tags accepted by `log()` family and visual methods (success() emits at
- * INFO severity but uses success styling). Useful for transport layers that
- * need to distinguish "success" from generic info logs.
+ * Tags aceptados por la familia `log()` y los métodos visuales (`success()`
+ * emite a severidad INFO pero usa styling de success). Útil para transports
+ * que necesitan distinguir "success" de logs info genéricos.
  */
 export type LogTag = LogLevel | typeof SUCCESS_LEVEL;
 /**
@@ -105,25 +102,25 @@ export type ExportFormat = 'json' | 'csv' | 'markdown' | 'plain' | 'html';
  */
 export type OutputFormat = 'auto' | 'plain' | 'ansi' | 'build' | 'ci';
 /**
- * Output modes for controlling where logs are written
+ * Modos de output para controlar dónde se escriben los logs.
  * @typedef {'console' | 'silent' | 'custom'} OutputMode
  *
  * @description
- * - console: Standard console.log output (default)
- * - silent: No output at all
- * - custom: Use custom OutputWriter for advanced scenarios
+ * - console: Output estándar vía `console.log` (default)
+ * - silent: Sin output
+ * - custom: Usa un `OutputWriter` custom para escenarios avanzados
  */
 export type OutputMode = 'console' | 'silent' | 'custom';
 /**
- * Custom output writer interface for redirecting log output
+ * Interfaz de output writer custom para redirigir el output de logs.
  *
  * @interface OutputWriter
  *
  * @description
- * Allows redirecting log output to custom destinations like:
- * - DraftLog for CLI spinners with concurrent logging
- * - Buffers for collecting logs during operations
- * - Custom streams or transports
+ * Permite redirigir el output de logs a destinos custom como:
+ * - DraftLog para CLI spinners con logging concurrente
+ * - Buffers para colectar logs durante operaciones
+ * - Streams o transports custom
  *
  * @example
  * class BufferWriter implements OutputWriter {
@@ -144,9 +141,24 @@ export interface OutputWriter {
     flush?(): void;
 }
 /**
- * Interfaz de configuración para instancias del logger
- *
- * @interface LoggerConfig
+ * Shape mínima de recurso OTel — duplicada aquí para evitar un import
+ * circular con `./transports.js`. El `ILogResource` canónico vive en
+ * `./transports.js`; ambos shapes se mantienen sincronizados vía el
+ * contrato público (service.name + version opcional + environment opcional).
+ */
+export interface ILogResourceRef {
+    'service.name': string;
+    'service.version'?: string;
+    'deployment.environment'?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Configuración de una instancia de `Logger`. Los campos booleanos activan
+ * o desactivan features visuales (colores, timestamps, stack traces); los
+ * campos selectores controlan tema, banner y formato de salida. Todos los
+ * campos son opcionales salvo `verbosity`, `enableColors` y
+ * `enableTimestamps`, que el constructor del logger rellena desde
+ * `DEFAULT_CONFIG` cuando no se proveen.
  *
  * @example
  * const config: LoggerConfig = {
@@ -161,18 +173,6 @@ export interface OutputWriter {
  *   autoDetectTheme: true
  * };
  */
-/**
- * Minimal OTel resource shape — duplicated here to avoid a circular
- * import with `./transports.js`. The canonical `ILogResource` lives in
- * `./transports.js`; both shapes stay in sync via the public contract
- * (service.name + optional version + optional environment).
- */
-export interface ILogResourceRef {
-    'service.name': string;
-    'service.version'?: string;
-    'deployment.environment'?: string;
-    [key: string]: string | undefined;
-}
 export interface LoggerConfig {
     globalPrefix?: string;
     verbosity: Verbosity;
@@ -184,15 +184,15 @@ export interface LoggerConfig {
     bufferSize?: number;
     autoDetectTheme?: boolean;
     outputFormat?: OutputFormat;
-    /** Output mode: 'console' (default), 'silent', or 'custom'*/
+    /** Modo de output: 'console' (default), 'silent' o 'custom'. */
     outputMode?: OutputMode;
-    /** Custom writer when outputMode is 'custom'*/
+    /** Writer custom cuando outputMode es 'custom'. */
     outputWriter?: OutputWriter;
-    /** CLI verbosity level for controlling primitive output*/
+    /** Nivel de verbosidad CLI para controlar el output primitivo. */
     cliLevel?: CLILogLevel;
     /**
-     * Default OTel resource attached to every record that doesn't override it.
-     * Set once per process (service.name, service.version, deployment.environment).
+     * Recurso OTel por defecto adjuntado a cada record que no lo sobreescriba.
+     * Se setea una vez por proceso (service.name, service.version, deployment.environment).
      */
     resource?: Partial<ILogResourceRef>;
 }
@@ -250,10 +250,11 @@ export interface AdaptiveColors {
  */
 export type SpacingType = 'compact' | 'normal' | 'spacious';
 /**
- * Configuración de layout para la estructura del log
+ * Layout de la línea de log: spacing entre elementos, padding interior,
+ * margen externo y separador entre partes. Lo consume el renderer para
+ * estructurar la salida visual.
  *
  * @interface LogLayout
- * @description Define cómo se organizan visualmente los elementos del log
  */
 export interface LogLayout {
     spacing: SpacingType;
@@ -262,10 +263,11 @@ export interface LogLayout {
     separator?: string;
 }
 /**
- * Configuración para partes individuales del log
+ * Estilo de un elemento individual del log (timestamp, level, prefix,
+ * mensaje, location). Cada campo es opcional y se aplica solo al elemento
+ * seleccionado sin tocar el resto de la línea.
  *
  * @interface LogPartConfig
- * @description Permite personalizar cada elemento del log por separado
  *
  * @example
  * const timestampConfig: LogPartConfig = {
@@ -289,10 +291,11 @@ export interface LogPartConfig {
     uppercase?: boolean;
 }
 /**
- * Configuración completa de estilos del log
+ * Estilos globales del log: layout, configuración por elemento (timestamp,
+ * level, prefix, mensaje, location) y props visuales de fondo (backdrop,
+ * transparency).
  *
  * @interface LogStyles
- * @description Agrupa todas las opciones de estilo en una sola configuración
  */
 export interface LogStyles {
     layout?: LogLayout;
@@ -304,12 +307,35 @@ export interface LogStyles {
     backdrop?: string;
     transparency?: number;
 }
+/**
+ * Resultado de un timer completado. Lo retorna internamente `Logger.timeEnd`
+ * y lo pasan los hooks en `extra` para mediciones de rendimiento.
+ *
+ * @property label - Etiqueta con la que se registró el timer vía `time(label)`.
+ * @property duration - Milisegundos transcurridos entre `startTime` y `endTime`.
+ * @property startTime - Marca temporal de inicio (`performance.now()` o `Date.now()`).
+ * @property endTime - Marca temporal de fin.
+ */
 export interface TimerResult {
     label: string;
     duration: number;
     startTime: number;
     endTime: number;
 }
+/**
+ * Contrato del logger retornado por los factory de scope (`Logger.component`,
+ * `Logger.scope`). Expone los métodos de log por nivel más una API fluida
+ * para badges, timers y estilos.
+ *
+ * Los métodos de log (`debug`, `info`, ...) devuelven `void`; los métodos de
+ * configuración (`badges`, `badge`, `clearBadges`, `style`) devuelven `this`
+ * para permitir encadenamiento.
+ *
+ * @example
+ * const auth = logger.component('Auth');
+ * auth.badge('JWT').info('Token validado');
+ * auth.style('cyberpunk').success('Login OK');
+ */
 export interface IScopedLogger {
     debug(...args: any[]): void;
     info(...args: any[]): void;
@@ -325,32 +351,101 @@ export interface IScopedLogger {
     timeEnd(label: string): number | undefined;
     style(presetName: string): this;
 }
+/**
+ * Logger especializado para servicios API. Extiende {@link IScopedLogger} con
+ * verbosidades específicas de backend: latencia (`slow`), rate limiting
+ * (`rateLimit`), fallos de credenciales (`auth`) y endpoints legacy
+ * (`deprecated`).
+ */
 export interface IAPILogger extends IScopedLogger {
     slow(message: string, duration?: number): void;
     rateLimit(message: string): void;
     auth(message: string): void;
     deprecated(message: string): void;
 }
+/**
+ * Logger especializado para componentes UI. Extiende {@link IScopedLogger}
+ * con verbosidades de lifecycle: montaje/desmontaje (`lifecycle`), cambios
+ * de estado (`stateChange`) y diffs de props (`propsChange`). Útil para
+ * depurar re-renders y flujos de componentes sin inundar el log de ruido.
+ */
 export interface IComponentLogger extends IScopedLogger {
     lifecycle(event: string, message?: string): void;
     stateChange(from: string, to: string, data?: any): void;
     propsChange(changes: Record<string, any>): void;
 }
+/**
+ * Bindings inmutables que viajan con un logger scoped/child. Definen la
+ * "identidad" del logger para filtrado, agrupación y atribución en
+ * transports. Se propagan a través de `child()` y se merguean al construir
+ * el {@link TransportRecord} que reciben los transports.
+ *
+ * @property scope - Etiqueta lógica del scope (p.ej. `"Auth"`, `"API:Users"`).
+ * @property badges - Lista de badges a renderizar junto al mensaje.
+ * @property type - Categoría del logger: `'scope'` (genérico), `'api'` (verbosidades HTTP), `'component'` (UI lifecycle).
+ * @property context - Cadena jerárquica de contexto (parent → child) para traces anidados.
+ */
 export interface Bindings {
     scope?: string;
     badges?: string[];
     type?: 'scope' | 'api' | 'component';
     context?: string[];
 }
+/**
+ * Estilo visual del wrapper de un badge.
+ *
+ * - `'brackets'` — `[badge]`
+ * - `'rounded'` — `(badge)`
+ * - `'plain'` — `badge` (sin wrapper)
+ * - `'unicode'` — `「badge」`
+ * - `'pill'` — badge con fondo redondeado estilo pill (CSS)
+ */
 export type BadgeStyle = 'brackets' | 'rounded' | 'plain' | 'unicode' | 'pill';
+/**
+ * Formato de renderizado del timestamp en la línea de log.
+ *
+ * - `'iso'` — `2026-07-05T12:34:56.789Z` (default, sortable)
+ * - `'time'` — `12:34:56`
+ * - `'timeMs'` — `12:34:56.789`
+ * - `'relative'` — tiempo relativo al momento de carga del logger
+ * - `'elapsed'` — `+1.2s` transcurrido desde el primer log de la sesión
+ * - `'date'` — `2026-07-05 12:34:56` (local)
+ * - `'custom'` — delega al formateador custom registrado en el logger
+ */
 export type TimestampFormat = 'iso' | 'time' | 'timeMs' | 'relative' | 'elapsed' | 'date' | 'custom';
+/**
+ * Alineación horizontal de una celda dentro de una columna de
+ * `Logger.cliTable`.
+ */
 export type ColumnAlign = 'left' | 'right' | 'center';
+/**
+ * Definición de una columna para `Logger.cliTable`. `content` es la fuente
+ * del valor (clave del row o string fijo); los demás campos controlan layout
+ * y color.
+ *
+ * @property content - Clave del row a renderizar, o string fijo para todas las filas.
+ * @property width - Ancho fijo en caracteres; si se omite, se auto-detecta del contenido.
+ * @property align - Alineación del contenido dentro de la celda.
+ * @property color - Color del texto (hex, nombre CSS o nombre ANSI).
+ */
 export interface ColumnConfig {
     content: string;
     width?: number;
     align?: ColumnAlign;
     color?: string;
 }
+/**
+ * Opciones de presentación aplicables a un log individual. Controlan layout
+ * multi-columna, ancho máximo, modo clave-valor, estilo de badge y formato
+ * de timestamp — todo sin alterar el `LoggerConfig` global del logger.
+ *
+ * @property rightAlign - Texto alineado a la derecha del mensaje principal (p.ej. duración).
+ * @property columns - Definición de columnas para modo tabla.
+ * @property maxWidth - Ancho máximo del mensaje antes de truncar/wrap.
+ * @property keyValue - Si `true`, renderiza los argumentos como `clave: valor`.
+ * @property badgeStyle - Override del estilo de badge para esta entrada.
+ * @property timestampFormat - Override del formato de timestamp para esta entrada.
+ */
 export interface LogOptions {
     rightAlign?: string;
     columns?: ColumnConfig[];
@@ -360,44 +455,45 @@ export interface LogOptions {
     timestampFormat?: TimestampFormat;
 }
 /**
- * CLI verbosity levels for controlling primitive output
+ * Niveles de verbosidad CLI para controlar el output primitivo.
  */
 export type CLILogLevel = 'silent' | 'quiet' | 'normal' | 'verbose' | 'debug';
 /**
- * Handle returned by logger.spinner() for controlling spinner lifecycle
+ * Handle retornado por `logger.spinner()` para controlar el ciclo de vida
+ * del spinner.
  */
 export interface ISpinnerHandle {
-    /** Start the spinner animation */
+    /** Arranca la animación del spinner. */
     start(): void;
-    /** Stop the spinner without a status message */
+    /** Detiene el spinner sin mensaje de status. */
     stop(): void;
-    /** Stop the spinner with a success message */
+    /** Detiene el spinner con un mensaje de success. */
     succeed(msg?: string): void;
-    /** Stop the spinner with a failure message */
+    /** Detiene el spinner con un mensaje de failure. */
     fail(msg?: string): void;
-    /** Update the spinner text while running */
+    /** Actualiza el texto del spinner mientras corre. */
     text(msg: string): void;
 }
 /**
- * Options for logger.box() output
+ * Opciones para el output de `logger.box()`.
  */
 export interface IBoxOptions {
-    /** Title displayed in the top border */
+    /** Título mostrado en el borde superior. */
     title?: string;
-    /** Color of the border (hex, CSS name, or ANSI name) */
+    /** Color del borde (hex, nombre CSS o nombre ANSI). */
     borderColor?: string;
-    /** Border character style */
+    /** Estilo de caracteres del borde. */
     borderStyle?: 'single' | 'double' | 'rounded' | 'bold';
-    /** Inner padding lines (default: 0) */
+    /** Líneas de padding interior (default: 0). */
     padding?: number;
 }
 /**
- * Options for logger.cliTable() output
+ * Opciones para el output de `logger.cliTable()`.
  */
 export interface ITableOptions {
-    /** Column names to display (overrides auto-detection) */
+    /** Nombres de columnas a mostrar (sobreescribe la auto-detección). */
     columns?: string[];
-    /** Header labels (defaults to column names) */
+    /** Labels del header (default: nombres de columnas). */
     head?: string[];
 }
 //# sourceMappingURL=core.d.ts.map

package/dist/types/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/types/core.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/types/core.ts"],"names":[],"mappings":"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"}

package/dist/types/hooks.d.ts

@@ -1,9 +1,8 @@
 import type { LogLevel, StackInfo } from './core.js';
 /**
- * The payload passed to every hook callback. Hooks may return a partial
- * of this object to override individual fields; the manager merges the
- * result back into the entry chain.
- *
+ * Payload que recibe cada callback de hook. Los hooks pueden devolver un
+ * partial de este objeto para sobreescribir campos individuales; el manager
+ * mergea el resultado de vuelta a la cadena del entry.
  */
 export interface HookLogEntry {
     level: LogLevel;
@@ -15,28 +14,72 @@ export interface HookLogEntry {
     correlationId?: string;
     context?: Record<string, unknown>;
     /**
-     * Source hook event when emitted from an internal failure path
-     * (e.g. transport flush error → fires `onError` with `hookEvent: 'beforeLog'`).
+     * Evento de hook de origen cuando se emite desde un path de fallo interno
+     * (p.ej. error de flush en transport → dispara `onError` con `hookEvent: 'beforeLog'`).
      */
     hookEvent?: HookEvent;
-    /** Captured exception, if the hook fired because of a thrown error. */
+    /** Excepción capturada, si el hook se disparó por un error lanzado. */
     error?: Error;
     /**
-     * Hook-specific structured payload. Used by transports to surface
-     * dropped records, response codes, retry counts, etc.
+     * Payload estructurado específico del hook. Lo usan los transports para
+     * exponer records dropeados, response codes, retry counts, etc.
      */
     extra?: Record<string, unknown>;
 }
-/** The three hook events the manager dispatches.*/
+/**
+ * Eventos de hook que el {@link IHookManager} despacha en el pipeline de log.
+ *
+ * - `'beforeLog'` — antes de despachar el log a transports/handlers. El
+ *   callback puede mutar o reemplazar campos del {@link HookLogEntry} y el
+ *   resultado se propaga a los siguientes hooks y al log final.
+ * - `'afterLog'` — después de que el log se ha escrito. Solo efectivo para
+ *   side-effects (métricas, telemetría); mutar el entry aquí no cambia el
+ *   output ya emitido.
+ * - `'onError'` — cuando un transport o un hook lanza, o cuando un batch
+ *   agota reintentos. El callback recibe `entry.error` (la excepción) y
+ *   `entry.extra` (payload estructurado: dropped, status, retryCount, ...).
+ */
 export type HookEvent = 'beforeLog' | 'afterLog' | 'onError';
 /**
- * Hook callback signature. Async hooks are awaited in priority order;
- * a returned partial object overrides the entry's fields for downstream
- * hooks and the eventual log call.
+ * Firma del callback de hook. Los hooks async se awaitan en orden de prioridad;
+ * devolver un partial object sobreescribe los campos del entry para los hooks
+ * siguientes y para la llamada final al log.
  */
 export type HookCallback = (entry: HookLogEntry) => void | Partial<HookLogEntry> | Promise<void | Partial<HookLogEntry>>;
-/** Koa-style middleware used by `HookManager.use()`.*/
+/**
+ * Middleware estilo Koa para el pipeline de hooks.
+ *
+ * Recibe el {@link HookLogEntry} y una función `next()` que invoca al
+ * siguiente middleware en la cadena de prioridad. Si el middleware NO llama
+ * `next()`, corta la cadena y el log se descarta (útil para filtrado
+ * avanzado, sampling o redacción que decide no emitir).
+ *
+ * Se registra vía {@link IHookManager.use} y corre antes que cualquier
+ * callback de evento {@link HookEvent}, lo que lo hace ideal para
+ * cross-cutting concerns: correlación de trazas, redacción de PII,
+ * enriquecimiento con atributos globales, etc.
+ *
+ * @example
+ * // Descarta logs marcados como privados
+ * const privacyFilter: MiddlewareFn = (entry, next) => {
+ *   if (entry.context?.private === true) return; // no llama next() → se descarta
+ *   return next();
+ * };
+ */
 export type MiddlewareFn = (entry: HookLogEntry, next: () => void | Promise<void>) => void | Promise<void>;
+/**
+ * Registro interno de un callback de hook suscrito a un {@link HookEvent}.
+ *
+ * El manager construye este record al registrar un callback vía `on()` /
+ * `once()`; los usuarios normalmente no instancian este tipo directamente.
+ * Útil para inspección del estado del manager en tests y depuración.
+ *
+ * @property id - Identificador único asignado por el manager (usado por el unsubscribe handle).
+ * @property event - Evento al que está suscrito el callback.
+ * @property callback - Función invocada cuando se emite el evento.
+ * @property priority - Orden de ejecución (mayor = antes). Empates respetan orden de registro.
+ * @property once - Si `true`, el manager lo des-registra tras la primera invocación.
+ */
 export interface HookRegistration {
     id: string;
     event: HookEvent;
@@ -44,11 +87,46 @@ export interface HookRegistration {
     priority: number;
     once: boolean;
 }
+/**
+ * Registro interno de un middleware en la cadena del manager. Análogo a
+ * {@link HookRegistration} pero para la capa de {@link MiddlewareFn}, que
+ * corre antes que los callbacks de evento.
+ *
+ * @property id - Identificador único asignado por el manager.
+ * @property fn - Middleware registrado vía `use()`.
+ * @property priority - Orden dentro de la cadena (mayor = más al inicio).
+ */
 export interface MiddlewareRegistration {
     id: string;
     fn: MiddlewareFn;
     priority: number;
 }
+/**
+ * Contrato del manager de hooks.
+ *
+ * Orquesta el pipeline de middleware + eventos que envuelve cada llamada a
+ * `log()`. Permite suscribirse a puntos del ciclo de vida del log
+ * (`beforeLog`, `afterLog`, `onError`), transformar el {@link HookLogEntry}
+ * en vuelo, y registrar middleware estilo Koa para cross-cutting concerns
+ * (sampling, redacción de PII, enriquecimiento con correlación).
+ *
+ * Los métodos `on` / `once` / `use` devuelven una función de unsubscribe
+ * (patrón `Disposable`) para limpieza explícita — llamarla remueve el
+ * registro sin necesidad de pasar el callback original.
+ *
+ * @example
+ * const hooks: IHookManager = createManager();
+ * // Redacta campos sensibles antes de loguear
+ * hooks.on('beforeLog', (entry) => {
+ *   if (entry.context?.password) {
+ *     return { context: { ...entry.context, password: '***' } };
+ *   }
+ * });
+ * // Métricas de error de transport
+ * hooks.on('onError', async (entry) => {
+ *   metrics.increment('log.transport.error');
+ * });
+ */
 export interface IHookManager {
     on(event: HookEvent, callback: HookCallback, priority?: number): () => void;
     once(event: HookEvent, callback: HookCallback, priority?: number): () => void;

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

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/types/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAErD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,uEAAuE;IACvE,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,mDAAmD;AACnD,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;AAEzH,uDAAuD;AACvD,MAAM,MAAM,YAAY,GAAG,CACvB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAC/B,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,MAAM,WAAW,gBAAgB;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,YAAY,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IACzB,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IAC5E,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IAC9E,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC;IACvD,GAAG,CAAC,UAAU,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IAC7D,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACnE,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACvD"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/types/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAErD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,uEAAuE;IACvE,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;AAEzH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,YAAY,GAAG,CACvB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAC/B,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,YAAY,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,YAAY;IACzB,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IAC5E,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IAC9E,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC;IACvD,GAAG,CAAC,UAAU,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IAC7D,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACnE,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACvD"}

package/dist/types/index.d.ts

@@ -6,6 +6,6 @@ export { LOG_LEVELS, SUCCESS_LEVEL } from './core.js';
 export type { LogMetadata, ILogHandler, } from './handlers.js';
 export type { SerializerFn, SerializerContext, SerializerEntry, SerializerConfig, ISerializerRegistry, } from './serializers.js';
 export type { HookLogEntry, HookEvent, HookCallback, MiddlewareFn, HookRegistration, MiddlewareRegistration, IHookManager, } from './hooks.js';
-export type { TransportRecord, TransportOptions, TransportTarget, ITransport, IBufferedTransport, ITransportManager, ILogResource, ILogAttributes, LogAttributeValue, } from './transports.js';
+export type { TransportRecord, TransportOptions, TransportTarget, ITransport, IBufferedTransport, ITransportManager, ILogResource, ILogAttributes, LogAttributeValue, TransportRecordKind, TransportDispatchRecord, SpanRecord, Span, SpanAttributes, SpanAttributeValue, SpanStatus, } from './transports.js';
 export { LOG_LEVEL_TO_SEVERITY_NUMBER, LOG_LEVEL_TO_SEVERITY_TEXT, } from './transports.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EACR,QAAQ,EACR,MAAM,EACN,SAAS,EACT,YAAY,EACZ,aAAa,EACb,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,WAAW,EACX,SAAS,EACT,aAAa,EACb,SAAS,EACT,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,QAAQ,EACR,UAAU,EACV,eAAe,EACf,WAAW,EACX,YAAY,EACZ,UAAU,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,aAAa,EACb,eAAe,GAClB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAGtD,YAAY,EACR,WAAW,EACX,WAAW,GACd,MAAM,eAAe,CAAC;AAGvB,YAAY,EACR,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,GACtB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EACR,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,GACf,MAAM,YAAY,CAAC;AAGpB,YAAY,EACR,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,iBAAiB,GACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACH,4BAA4B,EAC5B,0BAA0B,GAC7B,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EACR,QAAQ,EACR,MAAM,EACN,SAAS,EACT,YAAY,EACZ,aAAa,EACb,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,WAAW,EACX,SAAS,EACT,aAAa,EACb,SAAS,EACT,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,QAAQ,EACR,UAAU,EACV,eAAe,EACf,WAAW,EACX,YAAY,EACZ,UAAU,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,aAAa,EACb,eAAe,GAClB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAGtD,YAAY,EACR,WAAW,EACX,WAAW,GACd,MAAM,eAAe,CAAC;AAGvB,YAAY,EACR,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,GACtB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EACR,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,GACf,MAAM,YAAY,CAAC;AAGpB,YAAY,EACR,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,UAAU,EACV,IAAI,EACJ,cAAc,EACd,kBAAkB,EAClB,UAAU,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACH,4BAA4B,EAC5B,0BAA0B,GAC7B,MAAM,iBAAiB,CAAC"}