⚡ ngx-smart-interceptor

---

🌟 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

Recurso	Descrição
🛡️ Circuit Breaker	Bloqueia temporariamente chamadas a endpoints com falhas repetidas, evitando sobrecarga de rede e do servidor.
⚡ Deduplicação de GETs	Compartilha uma única requisição em voo entre múltiplos componentes que consultam o mesmo endpoint simultaneamente.
🔄 Stale-While-Revalidate (SWR)	Entrega dados do cache instantaneamente enquanto revalida em segundo plano pela rede.
📶 Adaptive Network Loading	Detecta conexões lentas (2G/3G/Data-Saver) e injeta cabeçalhos adaptativos para o backend compactar payloads.
⏳ Fila Offline	Armazena mutações (POST, PUT, PATCH, DELETE) durante quedas de rede e reenvia automaticamente ao reconectar.
🔑 Auth Refresh (Pause & Resume)	Intercepta erros 401, pausa requisições concorrentes, renova o token e reexecuta todas automaticamente.
📈 Profiler de Performance	Monitora o tempo de resposta e emite alertas para requisições que ultrapassam limites aceitáveis.
🆔 Correlation IDs	Gera e anexa UUIDs (X-Correlation-ID) para rastreamento de ponta a ponta (Tracing).
🛑 Cancelamento por Rota	Cancela automaticamente requisições pendentes ao navegar para outra rota.
🪝 Global Error Hooks	Inversão de controle para tratamento de erros globais ou por status HTTP (ex: toasts, redirects).
🧪 Modo Mock Integrado	Permite mockar endpoints no cliente com delay configurável para desenvolvimento ágil.
🔓 Context Bypass	Permite ignorar o interceptor seletivamente em chamadas específicas 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 capturado:', err.userFriendlyMessage),
        statusActions: {
          401: () => console.warn('Sessão expirada. Redirecionando para login...'),
        },
      },
    }),
  ],
};

---

💡 Exemplos Avançados

1. Fila de Refresh Token (Pause & Resume)

import { inject } from '@angular/core';
import { provideSmartInterceptor } from 'ngx-smart-interceptor';
import { AuthService } from './auth.service';

export const smartInterceptorProvider = provideSmartInterceptor({
  authRefresh: {
    unauthorizedStatusCode: 401,
    refreshTokenCallback: () => {
      const auth = inject(AuthService);
      return auth.refreshToken(); // Deve retornar Observable<boolean>
    },
  },
});

2. Bypass de Interceptação

import { HttpClient, HttpContext } from '@angular/common/http';
import { inject } from '@angular/core';
import { BYPASS_SMART_INTERCEPTOR } from 'ngx-smart-interceptor';

export class DataService {
  private http = inject(HttpClient);

  getRawData() {
    return this.http.get('/api/raw-stream', {
      context: new HttpContext().set(BYPASS_SMART_INTERCEPTOR, true),
    });
  }
}

---

🏛️ Arquitetura Modular (Handlers)

O ngx-smart-interceptor foi projetado seguindo o Princípio da Responsabilidade Única (SRP) e Clean Architecture:

• smartInterceptor: Atua estritamente como o Orquestrador de Pipeline RxJS.
• CircuitBreakerHandler: Gerencia o estado de disjuntores por URL em memória.
• DeduplicationHandler: Controla o compartilhamento de observables de requisições GET em voo.
• AuthRefreshHandler: Coordena o bloqueio, renovação e re-execução de requisições autenticadas.
• OfflineQueueHandler: Enfileira requisições mutantes e sincroniza com o evento de rede online.
• SwrCacheHandler: Armazena caches efêmeros e reage aos eventos de navegação de rotas.

---

🤝 Contribuição

Contribuições são muito bem-vindas! Consulte o nosso Guia de Contribuição e o nosso Código de Conduta.

---

📄 Licença

Distribuído sob a licença MIT. Consulte LICENSE para mais detalhes.