⚡ ngx-smart-interceptor

Interceptor HTTP inteligente, resiliente e de nível corporativo para aplicações Angular modernas.

🌟 Por que usar o ngx-smart-interceptor?

Em aplicações corporativas, a camada HTTP precisa de muito mais do que apenas repassar chamadas. Redes instáveis, requisições duplicadas, travamentos por falhas em cascata de microsserviços e lentidões degradam a experiência do usuário.

O ngx-smart-interceptor centraliza resiliência, performance e observabilidade em um único interceptor funcional, sem sobrecarregar sua base de código com lógica repetitiva de infraestrutura.

🚀 Recursos Principais

• 🛡️ Circuit Breaker: Bloqueia temporariamente chamadas a endpoints com falhas repetidas.
• ⚡ Deduplicação de GETs: Compartilha requisições em voo entre múltiplos chamadores concorrentes.
• 🔄 Stale-While-Revalidate (SWR): Entrega dados em cache instantaneamente com revalidação em segundo plano.
• 📶 Adaptive Network Loading: Detecta redes lentas (2G/3G) e adiciona headers adaptativos.
• ⏳ Fila Offline: Enfileira requisições mutantes na queda da conexão e reexecuta no retorno online.
• 🔑 Auth Refresh (Pause & Resume): Pausa chamadas concorrentes ao receber 401, atualiza o token e retoma o fluxo.
• 📈 Performance Profiler: Notifica e loga requisições com tempo de resposta acima do limite.
• 🆔 Correlation IDs: Adiciona identificadores rastreáveis (X-Correlation-ID) automaticamente.
• 🛑 Cancelamento por Rota: Cancela streams pendentes em transições de navegação.
• 🪝 Global Error Hooks: Tratamento unificado de erros com normalização amigável.
• 🧪 Modo Mock: Simula respostas mockadas com atraso configurável no cliente.
• 🔓 Context Bypass: Permite contornar o interceptor via HttpContext.

📦 Instalação

npm install ngx-smart-interceptor

⚙️ Configuração Rápida

No seu app.config.ts (ou main.ts):

import { ApplicationConfig } from '@angular/core';
import { provideHttpClient, withInterceptors } from '@angular/common/http';
import { provideSmartInterceptor, smartInterceptor } from 'ngx-smart-interceptor';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withInterceptors([smartInterceptor])),
    provideSmartInterceptor({
      enableDeduplication: true,
      generateCorrelationIds: true,
      enableAdaptiveLoading: true,
      enableOfflineQueue: true,
      cancelOnRouteChange: true,
      enableStaleWhileRevalidate: true,
      circuitBreaker: {
        failureThreshold: 3,
        resetTimeoutMs: 10000,
      },
      retry: {
        maxAttempts: 3,
        backoffBaseMs: 1000,
        allowedStatusCodes: [503, 504, 0],
      },
      performance: {
        slowRequestThresholdMs: 2000,
        logToConsole: true,
      },
      hooks: {
        onGlobalError: (err) => console.error('Erro global:', err.userFriendlyMessage),
        statusActions: {
          401: () => console.warn('Sessão expirada. Redirecionando para login...'),
        },
      },
    }),
  ],
};

🏛️ Arquitetura Modular (Handlers)

A biblioteca aplica Clean Architecture e o Princípio da Responsabilidade Única (SRP):

• smartInterceptor: Orquestrador central do fluxo RxJS.
• CircuitBreakerHandler: Monitora taxas de falha e controla a abertura/fechamento do circuito.
• DeduplicationHandler: Rastreia chamadas GET em voo evitando processamento concorrente redundante.
• AuthRefreshHandler: Enfileira e sincroniza a renovação de tokens com RxJS BehaviorSubject.
• OfflineQueueHandler: Mantém as requisições em memória e escuta o evento online do navegador.
• SwrCacheHandler: Gerencia o cache efêmero e o cancelamento de streams via NavigationStart.

📄 Licença

Distribuído sob a licença MIT.