🔮 behavior2audit

one-eventsourcing-4-all — Event Sourcing transparente via Proxy. Nenhuma linha de código original alterada, zero configuração e 0% de atrito com a arquitetura atual de seus domínios!

🔗 Veja o nosso CHANGELOG.md para acompanhar as atualizações mais recentes.

📦 Instalação

npm install @vibe2founder/behavior2audit
# ou
yarn add @vibe2founder/behavior2audit
# ou
bun add @vibe2founder/behavior2audit

🚀 Como Funciona

behavior2audit atua por debaixo dos panos através da engine ES6 Proxy nativa da linguagem JavaScript. Ele transforma inteiramente qualquer objeto, controlador, domínio ou estrutura de dados em uma entidade baseada em Event Sourcing.

O poder? Todas as chamadas de método automaticamente emitem eventos hiper-tipados contendo Timestamp exato da execução, Payloads completos com argumentos e dados retornados, Metadata incluindo nome do alvo de proxy, além de um sistema interativo de Health Checks paralelos.

Zero Acoplamento: Em vez de poluir seus serviços com side-effects de logs invasivos ou injetar barramentos customizados aos pulos pelo código, utilizamos a injeção simples:

import { EventSourcingFactory } from "@vibe2founder/behavior2audit";

const service = EventSourcingFactory.wrap(new UserService());

service.$on(event => {
  // Recebendo eventos gerados de forma intrínseca.
  console.log(`Auditoria => ${event.type}: `, event.payload)
});

💡 Exemplo de Uso

import { EventSourcingFactory } from '@vibe2founder/behavior2audit';

class UserService {
  private users: string[] = [];

  addUser(name: string) {
    this.users.push(name);
    return { id: Math.random(), name };
  }

  getUsers() {
    return this.users;
  }
}

// 1. Instanciamos a classe original
const rawService = new UserService();

// 2. Encapsulamos com a Factory
const service = EventSourcingFactory.wrap(rawService, {
  healthIntervalMs: 5000, // Health a cada 5 segundos
  onEvent: (e) => console.log(`[LOG GLOBAL]: ${e.type} em ${e.metadata.method || 'system'}`)
});

// 3. Ouvindo eventos específicos desta instância
service.$on((event) => {
  if (event.type === 'method_return') {
    console.log(`Evento capturado! Método: ${event.metadata.method}`);
    console.log(`Payload:`, event.payload);
  }
});

// 4. Executando métodos normalmente (com tipagem preservada)
service.addUser("Alice");
service.addUser("Bob");

// O health check rodará em background até chamarmos service.$dispose()

🛠️ Como foi feito

Nossa prioridade máxima em @vibe2founder/vibe2founder é a Antifragilidade técnica — Evidence-first, Agentic-by-Construction. Com isso, esta ferramenta aplica uma inversão transparente ao invólucro do Objeto sem violar nenhuma de suas Invariantes Domain-Driven.

A mágica reside no mecanismo base do Proxy moderno com a armadilha de método get, rastreando funções acessadas e envelopando imediatamente a chamada (capturando Promises assíncronas organicamente, esperando suas resoluções antes do envio do sinal de evento).

Essa solution foi codificada 100% livre de dependências para não engessar o runtime da stack original, oferecendo uma pequena lib (menor que 5kb) hiper-performativa.

🧪 Como testar

Para garantir a qualidade, testamos via injeção cruzada na infraestrutura:

1. Dentro do terminal no modelo WSL.
2. Use instâncias locais do @vibe2founder/tests2dialects rodando via Bun (bun run test).
3. O teste simula classes customizadas para assegurar que propriedades e métodos aninhados sejam capturados e os logs globais sejam emitidos e inspecionados sem falsos positivos.

📚 API Reference

EventSourcingFactory.wrap<T>(target, options?)

Encapsula um objeto ou instância de classe com capacidades de Event Sourcing.

Parâmetros:

• target: O objeto ou instância de classe a ser encapsulado
• options (opcional): Configurações de comportamento
  • healthIntervalMs: Intervalo para o evento de health (default: 30000ms)
  • enableHealthCheck: Habilita/desabilita health check (default: true)
  • onEvent: Callback global para todos os eventos

Retorna: Objeto estendido com $on() e $dispose()

Eventos Emitidos

• method_return: Disparado após execução de qualquer método
• health_check: Disparado periodicamente para monitoramento

📄 License

MIT © Vibe2Founder Team