npm package: @josericardodainese/debug-decorator
Description: 🚀 TypeScript decorator library for comprehensive method execution logging with advanced features like metrics, profiling, security, and machine learning insights
Author: José Ricardo da Silva Dainese
Latest version: 2.0.5

# 🚀 Debug Decorator

[![npm version](https://badge.fury.io/js/debug-decorator.svg)](https://badge.fury.io/js/debug-decorator)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-14.0+-green.svg)](https://nodejs.org/)

Uma biblioteca TypeScript **enterprise-grade** que fornece um decorator para logar automaticamente toda a execução de métodos, incluindo parâmetros, valores intermediários, tempo de execução e resultados, com funcionalidades avançadas como métricas, profiling, segurança e insights de machine learning.

## 🚀 Características

- **Log automático** de execução de métodos
- **Captura de parâmetros** de entrada
- **Captura de valores de retorno**
- **Medição de tempo** de execução
- **Captura de logs intermediários** (console.log dentro do método)
- **Tratamento de erros** com logging
- **Configuração flexível** para diferentes cenários
- **Suporte a métodos assíncronos**
- **Logs formatados** com emojis para fácil identificação

## 📦 Instalação

```bash
npm install @josericardodainese/debug-decorator
```

## 🔧 Configuração

Certifique-se de que seu `tsconfig.json` tenha os decorators habilitados:

```json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}
```

## 📖 Uso Básico

### Decorator Simples

```typescript
import { debugMethod } from '@josericardodainese/debug-decorator';

class MinhaClasse {
  @debugMethod()
  meuMetodo(parametro: string): string {
    return `Olá ${parametro}!`;
  }
}
```

### Com Configurações Personalizadas

```typescript
import { debugMethod } from '@josericardodainese/debug-decorator';

class MinhaClasse {
  // Apenas com nome personalizado - todas as funcionalidades ativas por padrão
  @debugMethod({
    name: 'Cálculo Complexo'
  })
  calcularAlgo(valor: number): number {
    console.log('Passo 1:', valor);
    const resultado = valor * 2;
    console.log('Passo 2:', resultado);
    return resultado;
  }

  // Desabilitando algumas funcionalidades específicas
  @debugMethod({
    name: 'Método Simples',
    logParams: false,        // Não loga parâmetros
    logIntermediateValues: false  // Não captura console.log internos
  })
  metodoSimples(texto: string): string {
    console.log('Processando:', texto); // Este log não será capturado
    return texto.toUpperCase();
  }

  // Desabilitando completamente o logging
  @debugMethod({
    name: 'Método Silencioso',
    disableAll: true         // Desabilita todas as funcionalidades
  })
  metodoSilencioso(dados: any): any {
    console.log('Este log não será capturado pelo decorator');
    return { status: 'processado', dados };
  }
}
```

## ⚙️ Opções de Configuração

| Opção | Tipo | Padrão | Descrição |
|-------|------|--------|-----------|
| `name` | `string` | Nome do método | Nome personalizado para o log |
| `disableAll` | `boolean` | `false` | Desabilita todas as funcionalidades de logging |
| `logParams` | `boolean` | `true` | Se deve logar os parâmetros de entrada |
| `logReturn` | `boolean` | `true` | Se deve logar o valor de retorno |
| `logExecutionTime` | `boolean` | `true` | Se deve logar o tempo de execução |
| `logIntermediateValues` | `boolean` | `true` | Se deve capturar console.log internos |
| `includeTimestamp` | `boolean` | `true` | Se deve incluir timestamp nos logs |
| `logErrors` | `boolean` | `true` | Se deve logar erros |
| `logger` | `function` | `console.log` | Função de log personalizada |
| `truncateLongValues` | `boolean` | `true` | Se deve truncar valores muito longos (strings > 500 chars, arrays/objetos > 1000 chars) |
| `metrics` | `MetricsOptions` | `{}` | Métricas e analytics avançados |
| `structuredLogging` | `StructuredLoggingOptions` | `{}` | Logs estruturados e formatados |
| `profiling` | `ProfilingOptions` | `{}` | Profiling de performance detalhado |
| `smartLogging` | `SmartLoggingOptions` | `{}` | Logs inteligentes com análise automática |
| `security` | `SecurityOptions` | `{}` | Segurança e compliance |
| `ml` | `MachineLearningOptions` | `{}` | Machine Learning e análise preditiva |

**💡 Importante:**

- Todas as opções são `true` por padrão! Você só precisa configurar quando quiser desabilitar alguma funcionalidade.
- Use `disableAll: true` para desabilitar completamente o logging em um método.

## 🌟 Funcionalidades Avançadas

### 1. 📊 Métricas e Analytics

```typescript
@debugMethod({
  metrics: {
    performance: true,        // Histórico de performance
    frequency: true,          // Quantas vezes foi chamado
    errorRate: true,          // Taxa de erro
    avgExecutionTime: true    // Tempo médio de execução
  }
})
```

### 3. 📝 Logs Estruturados

```typescript
@debugMethod({
  structuredLogging: {
    format: 'json',           // JSON, CSV, XML, YAML
    include: ['params', 'return', 'performance'],
    customFields: {
      userId: () => getCurrentUser(),
      sessionId: () => getSessionId()
    }
  }
})
```

### 5. 🔍 Profiling de Performance

```typescript
@debugMethod({
  profiling: {
    memoryUsage: true,        // Uso de memória
    cpuUsage: true,           // Uso de CPU
    networkCalls: true,       // Chamadas de rede
    databaseQueries: true     // Queries de banco
  }
})
```

### 6. 🧠 Logs Inteligentes

```typescript
@debugMethod({
  smartLogging: {
    highlightChanges: true,   // Destaca mudanças
    anomalyDetection: true,   // Detecta anomalias
    suggestions: true         // Sugere otimizações
  }
})
```

### 8. 🔐 Segurança e Compliance

```typescript
@debugMethod({
  security: {
    maskSensitiveData: ['password', 'token'],
    auditTrail: true,
    gdprCompliant: true
  }
})
```

### 10. 🤖 Machine Learning

```typescript
@debugMethod({
  ml: {
    predictPerformance: true, // Prediz performance
    detectPatterns: true,     // Detecta padrões
    optimizeSuggestions: true // Sugere otimizações
  }
})
```

## 🎯 Exemplo Completo

```typescript
import { debugMethod } from '@josericardodainese/debug-decorator';

class ReservationService {
  // Apenas com nome personalizado - todas as funcionalidades ativas!
  @debugMethod({
    name: 'Cálculo de Data de Expiração'
  })
  calculateExpirationDate(
    companyReservationPurchaseDto: any,
    databaseCompanyReservation: any,
  ): string {
    // O decorator captura automaticamente:
    // - Parâmetros de entrada (companyReservationPurchaseDto, databaseCompanyReservation)
    // - Tempo de execução
    // - Valor de retorno
    
    const today = new Date();
    const reservationDate = new Date(
      companyReservationPurchaseDto.companyReservation.date
    );
    const timeToExpireMinutes = this.parseTimeToMinutes(
      databaseCompanyReservation.timeToExpire
    );
    const expirationDate = new Date(reservationDate.getTime() + timeToExpireMinutes * 60000);
    
    return expirationDate.toISOString();
  }

  // Sem configurações - usa todas as funcionalidades padrão
  @debugMethod()
  parseTimeToMinutes(time: string | null): number {
    // O decorator captura automaticamente:
    // - Parâmetro de entrada (time)
    // - Tempo de execução
    // - Valor de retorno (número calculado)
    
    if (!time) return 0;
    const [hours, minutes] = time.split(':').map(Number);
    return hours * 60 + minutes;
  }
}
```

## 📊 Exemplo de Saída

Quando você executa o método acima, verá logs como este:

```
============================================================
🚀 Executando método: Cálculo de Data de Expiração [2025-01-16T10:30:00.000Z]
📊 Total de parâmetros: 2
============================================================

📥 1. Parâmetros de entrada: {
  count: 2,
  params: [
    { index: 0, type: 'object', value: {...}, isObject: true },
    { index: 1, type: 'object', value: {...}, isObject: true }
  ]
}

📝 2. Logs intermediários: {
  count: 7,
  logs: [
    "1. Captura a data/hora atual: 2025-01-16T10:30:00.000Z",
    "2. Converte a data da reserva para Date: 2025-08-17T08:00:00.000Z",
    "3. Converte os tempos para minutos: 150",
    // ... mais logs ...
  ]
}

📤 3. Valor de retorno: {
  type: 'string',
  value: '2025-01-16T12:30:00.000Z',
  isObject: false
}

⏱️  4. Tempo de execução: 45ms

============================================================
✅ Método Cálculo de Data de Expiração finalizado
📋 Total de passos executados: 4
============================================================
```

## 🧪 Testes

Execute os testes com:

```bash
npm test
```

Para testes em modo watch:

```bash
npm run test:watch
```

## 🏗️ Build

Para compilar a biblioteca:

```bash
npm run build
```

Para desenvolvimento com watch:

```bash
npm run dev
```

## 📁 Estrutura do Projeto

```
debug-decorator/
├── src/
│   ├── index.ts              # Exportações principais
│   ├── types.ts              # Definições de tipos
│   ├── debug-method.ts       # Implementação do decorator
│   └── examples/             # Exemplos de uso
├── dist/                     # Código compilado
├── package.json
├── tsconfig.json
├── jest.config.js
└── README.md
```

## 🔍 Casos de Uso

- **Debug de métodos complexos** com muitos passos
- **Profiling de performance** em desenvolvimento
- **Auditoria de execução** para métodos críticos
- **Documentação automática** de fluxos de execução
- **Troubleshooting** de problemas em produção
- **Desenvolvimento rápido** - apenas `@debugMethod()` e pronto!
- **Controle granular** - habilite/desabilite funcionalidades específicas ou use `disableAll: true`

## ⚠️ Considerações

- O decorator funciona melhor com métodos que têm lógica clara e bem estruturada
- Para métodos muito simples, o overhead pode não valer a pena
- Em produção, considere desabilitar logs intermediários para melhor performance
- O decorator é compatível com métodos assíncronos e síncronos
- **Todas as funcionalidades são ativas por padrão** - configure apenas o que quiser desabilitar
- Use `disableAll: true` para métodos que não precisam de logging ou em produção
- Use `truncateLongValues: false` se precisar ver valores completos sem truncamento

## 🤝 Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para:

1. Reportar bugs
2. Sugerir novas funcionalidades
3. Enviar pull requests
4. Melhorar a documentação

## 📄 Licença

MIT License - veja o arquivo LICENSE para detalhes.