🚀 @decido/logger

Ecosistema Decido OS — Registro de eventos estructurado isomórfico, telemetría reactiva mediante sensores y protección de datos sensibles con cumplimiento estricto de políticas de seguridad.

Este módulo provee un sistema de registro de eventos de alta ingeniería para Decido OS, permitiendo a las aplicaciones capturar, estructurar y despachar logs a nivel de consola (Browser/Server) y suscriptores de eventos personalizados. Incorpora sensores de telemetría asíncronos y una capa inteligente de redacción de datos privados (PII) adaptada a cada nivel de seguridad.

📦 Instalación

Para aprovisionar este módulo dentro de las áreas del monorepo o consumirlo externamente:

pnpm add @decido/logger

🏗️ Arquitectura de Telemetría

El flujo de registro de eventos y telemetría de @decido/logger se procesa bajo el siguiente ciclo asíncrono y de privacidad:

graph TD
    A[Invocación de Sensor / Log] --> B{Filtro por Categorías}
    B -->|Excluido| Z[Fin del Evento]
    B -->|Permitido| C{Redactor de PII}
    C -->|Nivel de Seguridad Tier| D[Redactar Passwords/Secrets/Tokens]
    D --> E{Verificación de Throttling & Muestreo}
    E -->|Descartado| Z
    E -->|Aprobado| F[Isomorfismo de Consola]
    F -->|Browser| G[Formateador de Estilos CSS]
    F -->|Node Server| H[Formateador de Estilos ANSI]
    G --> I[Despacho a Suscriptores]
    H --> I
    I --> J[Ejecución de Callbacks de Telemetría]

🔧 Especificación de APIs Principales

| API / Método / Tipo | Tipo | Descripción | | :--- | :--- | :--- | | Logger | Class | Instancia principal del sistema de logging estructurado. | | probe(id, data, options) | Function | Registra una métrica o lectura puntual de telemetría en un sensor. | | probeStart(id, options) | Function | Inicia una medición asíncrona de telemetría y rendimiento, devolviendo una función para finalizar y reportar el ciclo. | | SecurityTier | Enum / Type | Define los niveles de seguridad ('debug' \| 'standard' \| 'maximum') que controlan las políticas de redacción de PII, muestreo y throttling. | | addLogsSubscriber(callback) | Function | Registra un listener personalizado para capturar eventos de log y métricas en tiempo real. | | removeLogsSubscriber(callback)| Function | Remueve un listener previamente registrado para evitar fugas de memoria. | | clearAllLogsSubscribers() | Function | Vacía por completo la pila de suscriptores activos. |

💡 Ejemplos de Consumo Práctico

1. Inicialización y Registro Isomórfico

El logger adapta dinámicamente su formato visual dependiendo de si se ejecuta en el navegador (usando estilos CSS nativos en consola) o en la terminal del servidor (usando códigos de escape ANSI).

import { Logger } from '@decido/logger';

const logger = new Logger({
  categories: ['AUTH', 'DB'],
  excludeCategories: ['SPAM'],
  isBrowser: typeof window !== 'undefined'
});

// Logs estructurados con categorías
logger.info('DB', 'Conexión a base de datos establecida exitosamente', { host: 'localhost', port: 5432 });
logger.warn('AUTH', 'Intento de inicio de sesión sospechoso detectado', { userId: 9928 });

2. Telemetría Asíncrona Avanzada (probe y probeStart)

Los sensores de telemetría permiten auditar eventos y medir el rendimiento de operaciones complejas, aplicando automáticamente políticas de muestreo (sampling) y de limitación de frecuencia (throttling).

import { probe, probeStart } from '@decido/logger';

// 1. Registro de métrica puntual con Sensor de Telemetría
probe('user_signup', { userId: 452 }, {
  level: 'info',
  security: 'standard'
});

// 2. Medición de rendimiento asíncrono
const endProbe = probeStart('api_request_duration', {
  level: 'debug',
  security: 'debug',
  sampleRate: 1.0 // Registrar el 100% de las muestras en modo depuración
});

try {
  await executeDatabaseQuery();
} finally {
  // Finaliza la medición, calculando automáticamente la duración en milisegundos
  endProbe({ status: 'success' });
}

3. Redacción Inteligente de Datos Sensibles (PII)

El sistema de seguridad analiza los payloads de forma recursiva y redacta campos altamente confidenciales (como contraseñas, secretos, tokens, credenciales) de acuerdo al SecurityTier activo. Lo hace de forma segura conservando intactos los tipos y prototipos complejos de JavaScript/TypeScript.

import { probe } from '@decido/logger';

const payload = {
  user: {
    username: 'julio_decido',
    password: 'superSecretPassword123', // Será redactado de forma segura
    geminiApiKey: 'AIzaSyExampleGeminiToken' // Será redactado de forma segura
  },
  meta: {
    createdAt: new Date(), // SE CONSERVA como instancia de Date
    validationRegex: /[a-z]+/g, // SE CONSERVA como RegExp
    errorDetails: new Error('Fallo crítico de conexión') // SE CONSERVA como Error
  }
};

// Emisión bajo nivel de seguridad Máximo (Maximum)
probe('user_login_attempt', payload, {
  security: 'maximum'
});

// Salida emitida de forma interna (el password y api key se reemplazan por '[REDACTED]'):
// {
//   user: { username: 'julio_decido', password: '[REDACTED]', geminiApiKey: '[REDACTED]' },
//   meta: { createdAt: Date, validationRegex: RegExp, errorDetails: Error }
// }

4. Suscriptores de Eventos y Callbacks Personalizados

Perfecto para canalizar métricas hacia paneles reactivos o tableros visuales de Decido OS en tiempo real.

import { addLogsSubscriber, removeLogsSubscriber } from '@decido/logger';

const mySubscriber = (event) => {
  console.log(`[Dashboard Sync] Evento recibido: ${event.message}`, event.payload);
};

// Suscribirse a la cola
addLogsSubscriber(mySubscriber);

// ... operaciones de logging ...

// Desuscribirse para prevenir Memory Leaks
removeLogsSubscriber(mySubscriber);

🛡️ Robustez y Suite de Pruebas

Este paquete cuenta con un blindaje del 100% de cobertura absoluta en sentencias, ramas, funciones y líneas, certificado bajo Vitest.

Ejecución de Pruebas Unitarias

Para correr las pruebas unitarias y verificar el cumplimiento de cobertura localmente:

# Correr tests unitarios
pnpm --filter @decido/logger test

# Correr tests con reporte detallado de cobertura
pnpm --filter @decido/logger test:coverage

Directrices de Cobertura Estricta (vitest.config.ts)

La compilación y validación del paquete exige un umbral del 100% en todas sus métricas. Cualquier modificación de código requiere la adición correspondiente de aserciones de pruebas unitarias para mantener este estándar libre de regresiones.